<!DOCTYPE html>
<html lang="en"><head>
<title>Shadow DOM</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<link rel="stylesheet" href="spec.css" type="text/css">
<link rel="stylesheet" href="prettify.css" type="text/css">
<link rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-WD" type="text/css">
</head>

<body>

<div class="head">

<div class="logo">
    <a href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a>
</div>

<h1>Shadow DOM</h1>
<h2 id="working-draft">W3C Working Draft 16 October 2012</h2>
<dl>
<dt>This version</dt>
    <dd><a href="http://www.w3.org/TR/2012/WD-shadow-dom-20121016/">http://www.w3.org/TR/2012/WD-shadow-dom-20121016/</a></dd>
<dt>Latest version</dt>
    <dd><a href="http://www.w3.org/TR/shadow-dom/">http://www.w3.org/TR/shadow-dom/</a></dd>
<dt>Latest editor's draft</dt>
    <dd><a href="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/index.html">http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/index.html</a></dd>
<dt>Previous version</dt>
    <dd><a href="http://www.w3.org/TR/2012/WD-shadow-dom-20120522/">http://www.w3.org/TR/2012/WD-shadow-dom-20120522/</a></dd>
<dt>Revision history</dt>
    <dd><a href="http://dvcs.w3.org/hg/webcomponents/log/tip/spec/shadow/index.html">http://dvcs.w3.org/hg/webcomponents/log/tip/spec/shadow/index.html</a></dd>
<dt>Participate</dt>
    <dd>Discuss on <a href="http://lists.w3.org/Archives/Public/public-webapps/">public-webapps@w3.org</a> (<a href="http://www.w3.org/2008/webapps/">Web Applications Working Group</a>)</dd>
    <dd><a href="https://www.w3.org/Bugs/Public/enter_bug.cgi?comment=&amp;blocked=14978&amp;short_desc=%5BShadow%5D%3A%20&amp;product=WebAppsWG&amp;component=Component%20Model">File bugs</a> (w3.org's <a href="https://www.w3.org/Bugs/Public/">Bugzilla</a>)</dd>
<dt>Editor</dt>
    <dd class="vcard"><span class="fn">Dimitri Glazkov</span>, <span class="org">Google</span>, &lt;<a class="email" href="mailto:dglazkov@chromium.org">dglazkov@chromium.org</a>&gt;</dd>
</dl>

<p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2012 <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href="http://www.ercim.eu/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p>

<hr>

<h2 id="abstract">Abstract</h2>

<p>This specification describes a method of establishing and maintaining functional boundaries between DOM subtrees and how these subtrees interact with each other within a document tree, thus enabling better functional encapsulation within DOM.</p>

<h2 id="status">Status of This Document</h2>

<p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current <abbr title="World Wide Web Consortium">W3C</abbr> publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/"><abbr title="World Wide Web Consortium">W3C</abbr> technical reports index</a> at http://www.w3.org/TR/.</em></p>

<p>This document was published by the <a href="http://www.w3.org/2008/webapps/">Web Applications Working Group</a> as a Working Draft. If you wish to make comments regarding this document, please send them to <a href="mailto:public-webapps@w3.org">public-webapps@w3.org</a> (<a href="mailto:public-webapps-request@w3.org?subject=subscribe">subscribe</a>, <a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>). All feedback is welcome.</p><p>Publication as a Working Draft does not imply endorsement by the <abbr title="World Wide Web Consortium">W3C</abbr> Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.</p>

<p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>. <abbr title="World Wide Web Consortium">W3C</abbr> maintains a <a href="http://www.w3.org/2004/01/pp-impl/42538/status" rel="disclosure">public list of any patent disclosures</a> made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.</p>

</div>

<section class="toc">
<h2 id="toc">Table of Contents</h2>
<ol>
    <li><a href="#about"><span class="section">1</span> About this Document</a></li>
    <li><a href="#dependencies"><span class="section">2</span> Dependencies</a></li>
    <li><a href="#terminology"><span class="section">3</span> Terminology</a></li>
    <li><a href="#introduction"><span class="section">4</span> Introduction</a>
    <ol>
        <li><a href="#functional-encapsulation-example"><span class="section">4.1</span> Functional Encapsulation Example</a></li>
    </ol></li>
    <li><a href="#shadow-dom-subtrees"><span class="section">5</span> Shadow DOM Subtrees</a>
    <ol>
        <li><a href="#upper-boundary-encapsulation"><span class="section">5.1</span> Upper-boundary Encapsulation</a></li>
        <li><a href="#lower-boundary-encapsulation"><span class="section">5.2</span> Lower-boundary Encapsulation</a></li>
        <li><a href="#matching-insertion-points"><span class="section">5.3</span> Matching Insertion Points</a></li>
        <li><a href="#selecting-nodes-distributed-to-insertion-points"><span class="section">5.4</span> Matching Children, Distributed To Insertion Points</a></li>
        <li><a href="#multiple-shadow-subtrees"><span class="section">5.5</span> Hosting Multiple Shadow Subtrees</a></li>
        <li><a href="#nested-shadow-subtrees"><span class="section">5.6</span> Nested Shadow Subtrees</a></li>
        <li><a href="#rendering-shadow-subtrees"><span class="section">5.7</span> Rendering Shadow Subtrees</a></li>
    </ol></li>
    <li><a href="#events"><span class="section">6</span> Events</a>
    <ol>
        <li><a href="#event-retargeting"><span class="section">6.1</span> Event Retargeting</a></li>
        <li><a href="#retargeting-related-target"><span class="section">6.2</span> Retargeting <code>relatedTarget</code></a></li>
        <li><a href="#retargeting-focus-events"><span class="section">6.3</span> Retargeting Focus Events</a></li>
        <li><a href="#events-that-are-always-stopped"><span class="section">6.4</span> Events that are Always Stopped</a></li>
        <li><a href="#event-dispatch"><span class="section">6.5</span> Event Dispatch</a></li>
        <li><a href="#event-retargeting-example"><span class="section">6.6</span> Event Retargeting Example</a></li>
    </ol></li>
    <li><a href="#styles"><span class="section">7</span> Styles</a>
    <ol>
        <li><a href="#css-variables"><span class="section">7.1</span> CSS Variables</a></li>
        <li><a href="#text-decoration-property"><span class="section">7.2</span> <code>text-decoration</code> Property</a></li>
        <li><a href="#host-at-rule"><span class="section">7.3</span> <code>@host</code> @-rule</a></li>
    </ol></li>
    <li><a href="#user-interaction"><span class="section">8</span> User Interaction</a>
    <ol>
        <li><a href="#ranges-and-selection"><span class="section">8.1</span> Ranges and Selections</a></li>
        <li><a href="#focus-navigation"><span class="section">8.2</span> Focus Navigation</a></li>
        <li><a href="#active-element"><span class="section">8.3</span> Active Element</a></li>
        <li><a href="#editing"><span class="section">8.4</span> Editing</a></li>
        <li><a href="#assistive-technology"><span class="section">8.5</span> Assistive Technology</a></li>
    </ol>
    </li>
    <li><a href="#html-elements"><span class="section">9</span> HTML Elements in Shadow DOM Subtrees</a>
    <ol>
        <li><a href="#inert-html-elements"><span class="section">9.1</span> Inert HTML Elements</a></li>
        <li><a href="#html-forms"><span class="section">9.2</span> HTML Forms</a></li>
    </ol></li>
    <li><a href="#html-elements-and-their-shadow-dom-subtrees"><span class="section">10</span> HTML Elements and Their Shadow DOM subtrees</a>
    </li><li><a href="#elements-and-dom-objects"><span class="section">11</span> Elements and DOM Objects</a>
    <ol>
        <li><a href="#shadow-root-object"><span class="section">11.1</span> <code>ShadowRoot</code> Object</a>
        <ol>
            <li><a href="#shadow-root-attributes"><span class="section">11.1.1</span> <code>ShadowRoot</code> Attributes</a></li>
            <li><a href="#shadow-root-methods"><span class="section">11.1.2</span> <code>ShadowRoot</code> Methods</a></li>
        </ol></li>
        <li><a href="#content-element"><span class="section">11.2</span> The <code>content</code> HTML element</a></li>
        <li><a href="#shadow-element"><span class="section">11.3</span> The <code>shadow</code> HTML element</a></li>
    </ol></li>
    <li><a href="#shadow-dom-example"><span class="section">12</span> Shadow DOM Example</a></li>
    <li><a href="#acknowledgements">Acknowledgements</a></li>
</ol>

</section>

<section class="math">

<h2 id="about"><span class="section">1</span> About this Document</h2>

<p>All diagrams, examples, notes, are non-normative, as well as sections explicitly marked as non-normative. Everything else in this specification is normative.</p>

<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in <a href="http://dev.w3.org/2006/xbl2/#refsRFC2119">RFC2119</a>. For readability, these words do not appear in all uppercase letters in this specification.</p>

<p>To help with layering and to avoid circular dependencies between various parts of specification, this document consists of three consecutive narratives:
</p><ol>
    <li>setting up the stage for the specification,</li>
    <li>explaining of the conceptual model and algorithms behind it, and</li>
    <li>expressing this model with DOM interfaces and HTML elements.</li>
</ol>
<p>In a sense, these parts can be viewed as <em>math</em>, which sets up the reasoning environment, <em>physics</em>, which is the theoretical reasoning about the concept, and <em>mechanics</em>, which is the practical application of this reasoning.</p>

<p>Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as <a href="http://en.wikipedia.org/wiki/Algorithm">algorithm</a>. The algorithms are defined in terms of processing equivalence. The <dfn id="dfn-processing-equivalence">processing equivalence</dfn> is a constraint imposed on the algorithm implementors, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.</p>

<h2 id="dependencies"><span class="section">2</span> Dependencies</h2>

<p>This document relies on the following specifications:</p>

<ul>
    <li><a href="http://www.w3.org/TR/CSS2/">CSS Level 2 Revision 1</a></li>
    <li><a href="http://www.w3.org/TR/cssom/">CSSOM</a></li>
    <li><a href="http://www.w3.org/TR/DOM-Level-3-Events/">DOM Level 3 Events</a></li>
    <li><a href="http://www.w3.org/TR/domcore/">DOM4 (DOM Core)</a></li>
    <li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">HTML</a></li>
    <li><a href="http://html5.org/specs/dom-parsing.html">DOM Parsing and Serialization</a></li>
    <li><a href="http://www.w3.org/TR/selectors/">Selectors Level 3</a></li>
    <li><a href="http://dev.w3.org/2006/webapi/selectors-api/">Selectors API Level 1</a></li>
</ul>

<h2 id="terminology"><span class="section">3</span> Terminology</h2>

<p>The following terms are used throughout the specification:

</p><dl>
<dt>DOM</dt>
    <dd>The <a href="http://www.w3.org/TR/domcore/">document object model</a></dd>
<dt>document</dt>
    <dd>The Document Object Model's underlying document</dd>
<dt>node</dt>
    <dd>Any DOM object that <a href="http://www.w3.org/TR/domcore/#concept-tree-participate">participates in a tree</a></dd>
<dt>element</dt>
    <dd>A DOM object that implements the <a href="http://www.w3.org/TR/domcore/#interface-element">Element</a> interface</dd>
<dt>DOM tree</dt>
    <dd>Any <a href="http://www.w3.org/TR/domcore/#trees">tree</a>, composed of DOM objects</dd>
<dt>DOM structure</dt>
    <dd>A DOM tree or fragment of a DOM tree</dd>
</dl>

</section>

<section class="physics">

<h2 id="introduction"><span class="section">4</span> Introduction</h2>

<p>Web application developers often encounter the need to provide <dfn id="dfn-encapsulation">encapsulation</dfn> of a DOM structure. Despite being part of one document tree, there are typically many functional fragments of DOM (or <dfn id="dfn-dom-subtree">DOM subtrees</dfn>), as well as assumptions about these fragments operating independently. This type of encapsulation is called <dfn id="dfn-functional-encapsulation">functional encapsulation</dfn>, as opposed to <dfn id="dfn-trust-encapsulation">trust encapsulation</dfn>, which deals with limiting information flow based on trust and ensuring security of data and state within an application.</p>

<p><a href="#dfn-functional-encapsulation">Functional encapsulation</a> is primarily concerned with establishing functional boundaries in a document tree. A functional boundary (or just <dfn id="dfn-boundary">boundary</dfn> hereon) is a delineation of functional concerns between two loosely coupled units of functionality.</p>

<h3 id="functional-encapsulation-example"><span class="section">4.1</span> Functional Encapsulation Example</h3>

<p>A Web application user interface is commonly composed of several user interface elements (or <dfn id="dfn-widget">widgets</dfn>), each a DOM subtree. In cases where a widget is tasked with hosting other widgets, the need arises for the widget to understand where its DOM subtree ends and another widget's DOM subtree begins.</p>

<object data="functional-encapsulation-example.svg" width="800" height="500"></object>

<p>This need for observing the functional <a href="#dfn-boundary">boundaries</a> in a document tree is even larger when a <a href="#dfn-widget">widget</a> is operated on—added, moved, or removed in the document tree—by an outside actor, such as the Web application that consumes these widgets. Unless the widget consumer knows exactly how a widget's DOM structure is designed, it is impossible for the consumer to reasonably operate on the widget. A typical workaround has been providing alternative means of operation by the widget developer, which, in striving for API consistency quickly extrapolates into a complete set of widget-specific, DOM-like APIs.</p>

<h2 id="shadow-dom-subtrees"><span class="section">5</span> Shadow DOM Subtrees</h2>

<p>To solve this problem at its core, a new abstraction is introduced. The <dfn id="dfn-shadow-dom">shadow DOM</dfn> allows multiple DOM subtrees (in addition to the document tree) to be composed into one larger tree when rendered. The existence of multiple DOM subtrees is enabled by letting any element in the document tree to host one or more additional DOM subtrees. These <dfn id="dfn-shadow-dom-subtree">shadow DOM subtrees</dfn> are governed by a set of rules that establish encapsulation <a href="#dfn-boundary">boundaries</a> while retaining the standard DOM composability semantics.</p>

<p>The encapsulation <a href="#dfn-boundary">boundaries</a> between shadow DOM subtrees are called <dfn id="dfn-shadow-boundary">shadow boundaries</dfn>. The elements that host shadow DOM subtrees are called <dfn id="dfn-shadow-host">shadow hosts</dfn>, and the root nodes of the shadow DOM subtrees are called <dfn id="dfn-shadow-root">shadow roots</dfn>.</p>

<object data="shadow-dom-subtrees.svg" width="800" height="430"></object>

<p>When rendered, the shadow DOM subtree takes place of the <a href="#dfn-shadow-host">shadow host</a>'s content.</p>

<object data="shadow-rendering.svg" width="450" height="400"></object>

<p>To enable composition of <a href="#dfn-shadow-host">shadow host</a>'s children and the shadow DOM subtree, a notion of insertion points is added to the abstraction. An <dfn id="dfn-insertion-point">insertion point</dfn> is a defined location in the shadow DOM subtree, to which the <a href="#dfn-shadow-host">shadow host</a>'s children are transposed when rendering. The mechanism that determines which <a href="#dfn-shadow-host">shadow host</a>'s children are transposed into which <a href="#dfn-insertion-point">insertion points</a> is called <dfn id="dfn-distribution">distribution</dfn>.</p>

<object data="insertion-points.svg" width="800" height="900"></object>

<p>Thus, the encapsulation of a shadow DOM subtree can be viewed as a two-fold problem:
</p><ol>
    <li>the <dfn id="dfn-upper-boundary-encapsulation">upper-boundary encapsulation</dfn>, or governing the boundary between the shadow root and the shadow host; and</li>
    <li>the <dfn id="dfn-lower-boundary-encapsulation">lower-boundary encapsulation</dfn>, or governing the boundary between the insertion points and the shadow host's children.</li>
</ol>

<h3 id="upper-boundary-encapsulation"><span class="section">5.1</span> Upper-boundary Encapsulation</h3>

<p>To maintain the upper-boundary encapsulation, the following <dfn id="dfn-scoping-constraints">scoping constraints</dfn> <strong>must</strong> apply to all nodes in a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>:</p>
<ul>
    <li>The <a href="http://www.w3.org/TR/domcore/#dom-node-ownerdocument"><code>ownerDocument</code></a> property refers to the document of the <a href="#dfn-shadow-host">shadow host</a></li>
    <li>The nodes and <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-document-nameditem-filter">named elements</a> <strong>are not</strong> accessible using <a href="#dfn-shadow-host">shadow host</a>'s document <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-tree-accessors">DOM tree accessors</a> or with <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window">Window</a> object <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#named-access-on-the-window-object">named properties</a></li>
    <li>The nodes <strong>are not</strong> present in any of the document's <a href="http://www.w3.org/TR/dom/#interface-nodelist"><code>NodeList</code></a>, <a href="http://www.w3.org/TR/dom/#interface-htmlcollection"><code>HTMLCollection</code></a>, or <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#domelementmap-0"><code>DOMElementMap</code></a> instances</li>
    <li>The nodes with a unique <a href="http://www.w3.org/TR/domcore/#concept-id">id</a> and <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-document-nameditem-filter">named elements</a> <strong>are not</strong> addressable from any attributes of elements in <a href="#dfn-shadow-host">shadow host</a>'s document</li>
    <li>The style sheets, represented by the nodes <strong>are not</strong> accessible using <a href="#dfn-shadow-host">shadow host</a> document's <a href="http://www.w3.org/TR/cssom/#extensions-to-the-document-interface">CSSOM extensions</a></li>
    <li>The nodes <strong>are</strong> accessible using <a href="#dfn-shadow-root">shadow root</a>'s DOM tree accessor methods</li>
    <li>The nodes with a unique <a href="http://www.w3.org/TR/domcore/#concept-id">id</a> and <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-document-nameditem-filter">named elements</a> <strong>are</strong> addressable from any attributes of elements in the same <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a></li>
    <li>The <a href="http://www.w3.org/TR/selectors/">selectors</a> <strong>must not</strong> cross the <a href="#dfn-shadow-boundary">shadow boundary</a> from the document tree into the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a></li>
</ul>
<p>For convenience, the <a href="#dfn-shadow-root">shadow root</a> provides its own set of DOM tree accessor methods. No nodes other than <a href="#dfn-shadow-root">shadow root</a> descendants are accessible with these methods.</p>

<p>The <a href="http://www.w3.org/TR/dom/#dom-node-parentnode"><code>parentNode</code></a> and <a href="http://www.w3.org/TR/dom/#dom-node-parentelement"><code>parentElement</code></a> attributes of the <a href="#dfn-shadow-root">shadow root</a> object <strong>must</strong> always return <code>null</code>.</p>

<h3 id="lower-boundary-encapsulation"><span class="section">5.2</span> Lower-boundary Encapsulation</h3>

<p>To maintain the lower-boundary encapsulation, the <a href="#dfn-distribution">distribution</a> of child nodes of the <a href="#dfn-shadow-host">shadow host</a> among the <a href="#dfn-insertion-point">insertion points</a> in the associated <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> <strong>must</strong> have the following traits:</p>
<ul>
    <li>The <a href="#dfn-distribution">distribution</a> does not affect the state of the document DOM tree or shadow DOM subtrees</li>
    <li>Each insertion point participates in <a href="#dfn-distribution">distribution</a> by providing a matching criteria for the child nodes. The <dfn id="dfn-matching-criteria">matching criteria</dfn> determines whether a given node could be <a href="#dfn-distribution">distributed</a> to a given insertion point</li>
    <li>The <a href="#dfn-distribution">distribution</a> is a result of executing a stable algorithm</li>
    <li>The <a href="#dfn-distribution">distribution</a> itself does not change the variables affecting the <a href="#dfn-distribution">distribution</a></li>
    <li>The <a href="#dfn-distribution">distribution</a> reoccurs whenever any variable affecting it is changed</li>
</ul>

<p>An <a href="#dfn-insertion-point">insertion point</a> may be <strong>active</strong> or <strong>inactive</strong>. An <dfn id="dfn-active-insertion-point">active</dfn> insertion point participates in the <a href="#dfn-distribution">distribution</a> process, whereas the <dfn id="dfn-inactive-insertion-point">inactive</dfn> insertion does not. If not specifically set to be inactive, the insertion point <strong>must</strong> be considered <strong>active</strong>.</p>

<p>If an <a href="#dfn-insertion-point">insertion point</a> is not in a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, it <strong>must</strong> have the same rendering behavior as the <a href="http://www.whatwg.org/specs/web-apps/current-work/#htmlunknownelement"><code>HTMLUnknownElement</code></a>.</p>

<p>The <dfn id="dfn-distribution-algorithm">distribution algorithm</dfn> <strong>must</strong> produce an outcome that is <a href="#dfn-processing-equivalence">equivalent</a> of the outcome of processing these steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>TREE</var>, a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a></dd>
    <dd><var>POOL</var>, a list of DOM nodes</dd>
<dt>Output</dt>
    <dd>The nodes in <var>POOL</var> are <a href="#dfn-distribution">distributed</a> among <a href="#dfn-insertion-point">insertion points</a> in <var>TREE</var>.</dd>
</dl>

<ol>
    <li><dfn id="algo-distribution-repeat-outer">Repeat</dfn> for each <a href="#dfn-active-insertion-point">active</a> <a href="#dfn-insertion-point">insertion point</a> in <var>TREE</var>, in <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#tree-order">tree order</a>:
    <ol>
        <li>Let <var>POINT</var> be the current insertion point</li>
        <li><dfn id="algo-distribution-repeat">Repeat</dfn> for each node in <var>POOL</var>:
        <ol>
            <li>Let <var>NODE</var> be the current node</li>
            <li>If the <var>NODE</var> matches <var>POINT</var>'s <a href="#dfn-matching-criteria">matching criteria</a>:
                <ol>
                    <li><a href="#dfn-distribution">Distribute</a> the <var>NODE</var> to <var>POINT</var></li>
                    <li>Remove <var>NODE</var> from the <var>POOL</var></li>
                </ol></li>
            <li>Otherwise, continue to <a href="#algo-distribution-repeat">repeat</a></li>
        </ol></li>
        <li>Continue to <a href="#algo-distribution-repeat-outer">repeat</a></li>
    </ol></li>
</ol>
</div>

<h3 id="matching-insertion-points"><span class="section">5.3</span> Matching Insertion Points</h3>

<p>The <a href="#dfn-matching-criteria">matching criteria</a> for <a href="#dfn-insertion-point">insertion point</a> is defined as a set of selector fragments. Each <dfn id="dfn-selector-fragment">selector fragment</dfn> is indeed a fragment in the <a href="http://www.w3.org/TR/css3-selectors">selector</a> <code>(shadow-host)&gt;(fragment)</code>, where <code>(shadow-host)</code> is a selector that uniquely identifies the <a href="#dfn-shadow-host">shadow host</a>, and <code>(fragment)</code> is the <a href="#dfn-selector-fragment">selector fragment</a>.</p>

<p>A <dfn id="dfn-valid-selector-fragment">valid selector fragment</dfn> may contain:</p>

<ul>
    <li>A <a href="http://www.w3.org/TR/css3-selectors/#type-selectors">type selector</a> or a <a href="http://www.w3.org/TR/css3-selectors/#universal-selector">universal selector</a></li>
    <li><a href="http://www.w3.org/TR/css3-selectors/#class-html">class selector(s)</a></li>
    <li>An <a href="http://www.w3.org/TR/css3-selectors/#id-selectors">ID selector</a></li>
    <li><a href="http://www.w3.org/TR/css3-selectors/#attribute-selectors">attribute selector(s)</a></li>
    <li>the following <a href="http://www.w3.org/TR/css3-selectors/#pseudo-classes">pseudo-class selector(s)</a>:
        <ul>
            <li><code>:link</code></li>
            <li><code>:visited</code></li>
            <li><code>:target</code></li>
            <li><code>:enabled</code></li>
            <li><code>:disabled</code></li>
            <li><code>:checked</code></li>
            <li><code>:indeterminate</code></li>
            <li><code>:nth-child()</code></li>
            <li><code>:nth-last-child()</code></li>
            <li><code>:nth-of-type()</code></li>
            <li><code>:nth-last-of-type()</code></li>
            <li><code>:first-child</code></li>
            <li><code>:last-child</code></li>
            <li><code>:first-of-type</code></li>
            <li><code>:last-of-type</code></li>
            <li><code>:only-of-type</code></li>
        </ul>
    </li>
</ul>

<p>If any other types of selectors are present in the <a href="#dfn-selector-fragment">selector fragment</a>, the fragment <strong>must</strong> be considered invalid.</p>

<p>A conforming UAs <strong>must</strong> consider a node as <dfn id="#dfn-content-matching">matching</dfn> a set of <a href="#dfn-selector-fragment">selector fragments</a> in the context of a given <a href="#dfn-shadow-host">shadow host</a>, if it:
</p><ol>
    <li>is a child node of the shadow host; and</li>
    <li>all <a href="#dfn-selector-fragment">selector fragments</a> in the set are <a href="#dfn-valid-selector-fragment">valid</a>; and</li>
    <li>child node matches at least one selector fragment in the set or the set is empty.</li>
</ol>

<h3 id="selecting-nodes-distributed-to-insertion-points"><span class="section">5.4</span> Matching Children, Distributed To Insertion Points</h3>

<p><a href="http://dev.w3.org/csswg/selectors4/#idref-combinators">Reference combinators</a> match the children of a <a href="#dfn-shadow-host">shadow host</a>, <a href="#dfn-distribution">distributed</a> to the <a href="#dfn-insertion-point">insertion points</a> within a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>. To match, all of these conditions <strong>must</strong> apply:</p>
<ul>
    <li>The combinator value <strong>must</strong> be <code>select</code></li>
    <li>The first compound selector of the combinator <strong>must</strong> match an <a href="#dfn-insertion-point">insertion point</a></li>
    <li>The second compound selector <strong>must</strong> match an element, <a href="#dfn-distribution">distributed</a> to this <a href="#dfn-insertion-point">insertion point</a></li>
</ul>
<p>For example, <code class="prettify">.some-insertion-point /select/ div.special</code> will match all <code>div</code> elements that have <code>class</code> attribute set to <code>special</code> and have been <a href="#dfn-distribution">distributed</a> to an insertion point that has a class attribute set to <code>some-insertion-point</code>.</p>

<p>All other types of selectors <strong>must not</strong> cross the <a href="#dfn-shadow-boundary">shadow boundary</a> from a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> to the tree of its <a href="#dfn-shadow-host">shadow host</a>.</p>


<h3 id="multiple-shadow-subtrees"><span class="section">5.5</span> Hosting Multiple Shadow Subtrees</h3>

<p>A <a href="#dfn-shadow-host">shadow host</a> may host more than one <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>. In such cases, the subtrees are stacked in the order they were added the host, starting with the subtree added most recently. This set of trees is called a <dfn id="dfn-tree-stack">tree stack</dfn>. The more recently added subtree is called the <dfn id="dfn-younger-tree">younger tree</dfn>, and the less recently added subtree is called the <dfn id="dfn-older-tree">older tree</dfn>. The most recently added subtree is called the <dfn id="dfn-youngest-tree">youngest tree</dfn>.</p>

<p>To facilitate composing multiple shadow subtrees of the same host, a special kind of <a href="#dfn-insertion-point">insertion point</a> is defined. The <dfn id="dfn-shadow-insertion-point">shadow insertion point</dfn> designates a place in the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, where an <a href="#dfn-older-tree">older tree</a> is inserted when rendering. If multiple <a href="#dfn-shadow-insertion-point">shadow insertion points</a> exist in a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, only the first, in <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#tree-order">tree order</a>, is recognized. It is said that the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> is <dfn id="dfn-assigned">assigned</dfn> to a <a href="#dfn-shadow-insertion-point">shadow insertion point</a> if the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> is rendered in place of this <a href="#dfn-shadow-insertion-point">shadow insertion point</a>.</p>

<p>Just like other <a href="#dfn-insertion-point">insertion points</a>, the <a href="#dfn-shadow-insertion-point">shadow insertion points</a> can be <a href="#dfn-active-insertion-point">active</a> or <a href="#dfn-inactive-insertion-point">inactive</a>.</p>

<p>The composition is performed with the <dfn id="dfn-tree-composition">tree composition algorithm</dfn>, which <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:

</p><div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>HOST</var>, a <a href="#dfn-shadow-host">shadow host</a></dd>
<dt>Output</dt>
    <dd>All <a href="#dfn-insertion-point">insertion points</a> and <a href="#dfn-shadow-insertion-point">shadow insertion points</a> are populated.</dd>
</dl>

<ol>
    <li>Let <var>TREE</var> be the <a href="#dfn-youngest-tree">youngest tree</a> in the <var>HOST</var>'s <a href="#dfn-tree-stack">tree stack</a>
    </li><li>Let <var>POOL</var> be the list of nodes</li>
    <li>Populate <var>POOL</var> with child nodes of the <var>HOST</var></li>
    <li><dfn id="algo-composition-repeat">Repeat</dfn> while <var>TREE</var> exists:
    <ol>
        <li>Let <var>POINT</var> be the first encountered <a href="#dfn-active-insertion-point">active</a> <a href="#dfn-shadow-insertion-point">shadow insertion point</a> in <var>TREE</var>, in <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#tree-order">tree order</a>
        </li><li>Run the <a href="#dfn-distribution-algorithm">distribution algorithm</a>, supplying <var>POOL</var> and <var>TREE</var> as input</li>
        <li>If <var>POINT</var> exists:
        <ol>
            <li>Find the next older tree, relative to <var>TREE</var> in the <var>HOST</var>'s <a href="#dfn-tree-stack">tree stack</a>
            <ol>
                <li>If there is no older tree:
                <ol>
                    <li><a href="#dfn-distribution">Distribute</a> remaining nodes in <var>POOL</var>, if any, to <var>POINT</var></li>
                    <li><strong>stop</strong>.</li>
                </ol></li>
                <li>Otherwise:
                <ol>
                    <li>Set <var>TREE</var> to be this older tree</li>
                    <li><a href="#dfn-assigned">Assign</a> <var>TREE</var> to the <var>POINT</var></li>
                    <li>Continue to <a href="#algo-composition-repeat">repeat</a></li>
                </ol></li>
            </ol></li>
        </ol></li>
        <li>Otherwise, <strong>stop</strong>.
    </li></ol></li>
</ol>
</div>

<p>When an <a href="#dfn-insertion-point">insertion point</a> or a <a href="#dfn-shadow-insertion-point">shadow insertion point</a> has nothing <a href="#dfn-assigned">assigned</a> or <a href="#dfn-distribution">distributed</a> to them, the fallback content <strong>must</strong> be used instead when rendering. The <dfn id="dfn-fallback-content">fallback content</dfn> is all descendants of the DOM element that represents the insertion point. The <a href="#dfn-insertion-point">insertion points</a> or <a href="#dfn-shadow-insertion-point">shadow insertion points</a> in fallback content <strong>must</strong> be considered <a href="#dfn-inactive-insertion-point">inactive</a>.</p>

<h3 id="nested-shadow-subtrees"><span class="section">5.6</span> Nested Shadow Subtrees</h3>

<p>Any element in a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> can be a <a href="#dfn-shadow-host">shadow host</a>, thus producing nested shadow DOM subtrees. A shadow DOM subtree is <dfn id="dfn-nested-subtree">nested</dfn> when its <a href="#dfn-shadow-host">shadow host</a> is itself a part of a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>.</p>

<p>A <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> is <dfn id="dfn-enclosed-subtree">enclosed</dfn> by another <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> when the enclosing subtree nests the enclosed subtree through one or more levels of nesting.</p>

<h3 id="rendering-shadow-subtrees"><span class="section">5.7</span> Rendering Shadow DOM Subtrees</h3>

<p><dfn id="dfn-rendering">Rendering</dfn> of <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>, or presenting them visually, is defined as a specialization of rendering <strong>any DOM subtree</strong>, and <strong>must</strong> happen as these steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>HOST</var>, a <a href="#dfn-shadow-host">shadow host</a></dd>
<dt>Output</dt>
    <dd>Rendering of the <var>HOST</var>, including its <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a></dd>
</dl>

<ol>
    <li>Run <a href="#dfn-tree-composition">tree composition algorithm</a> for the given <a href="#dfn-shadow-host">shadow host</a></li>
    <li>As content of the <a href="#dfn-shadow-host">shadow host</a>, render the <a href="#dfn-youngest-tree">youngest tree</a> as a <strong>any DOM subtree</strong>, with the following <dfn id="dfn-shadow-rendering">shadow rendering</dfn> exceptions:
    <ul>
        <li>Each element that is a <a href="#dfn-shadow-host">shadow host</a> <strong>must</strong> be <a href="#dfn-rendering">rendered</a> accordingly</li>
        <li>In place of each <a href="#dfn-insertion-point">insertion point</a>, process the following <dfn id="dfn-insertion-point-rendering">insertion point rendering</dfn> steps:
        <ol>
            <li>If there are child nodes <a href="#dfn-distribution">distributed</a> to this insertion point, for each child node and in the order they were distributed:
            <ol>
                <li>Let <var>CHILD</var> be the child node being rendered</li>
                <li>If <var>CHILD</var> is itself an <a href="#dfn-insertion-point">insertion point</a>, and the tree being rendered is <a href="#dfn-nested-subtree">nested</a>, render them using <a href="#dfn-insertion-point-rendering">insertion point rendering</a> steps</li>
                <li>Otherwise, render <var>CHILD</var> as <strong>any DOM subtree</strong>
            </li></ol></li>
            <li>Otherwise, render <a href="#dfn-fallback-content">fallback content</a> as <strong>any DOM subtree</strong></li>
        </ol></li>
        <li>In place of each <a href="#dfn-shadow-insertion-point">shadow insertion point</a>:
        <ol>
            <li>If there is an <a href="#dfn-older-tree">older tree</a>, <a href="#dfn-assigned">assigned</a> to this shadow insertion point, render it as <strong>any DOM subtree</strong>, but with the same <a href="#dfn-shadow-rendering">shadow rendering</a> exceptions.</li>
            <li>Otherwise, render <a href="#dfn-fallback-content">fallback content</a> as <strong>any DOM subtree</strong></li>
        </ol></li>
    </ul></li>
</ol>
</div>

<p>This process of <a href="#dfn-rendering">rendering</a> produces a structure that is a composition of several DOM subtrees, including the document tree. The term "<dfn id="dfn-as-rendered">as rendered</dfn>" is used to refer to this structure.</p>

<h2 id="events"><span class="section">6</span> Events</h2>

<p>When an <a href="http://www.w3.org/TR/domcore/#events">event</a> is <a href="http://www.w3.org/TR/domcore/#dispatching-events">dispatched</a> in a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, its path either crosses the <a href="#dfn-shadow-boundary">shadow boundary</a> or is terminated at the <a href="#dfn-shadow-boundary">shadow boundary</a>. One exception are the mutation events. The <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-eventgroupings-mutationevents">mutation event types</a> <strong>must</strong> never be dispatched in a shadow DOM subtree.</p>

<p>For event path to cross the <a href="#dfn-shadow-boundary">shadow boundary</a>, it <strong>must</strong> be populated with <dfn id="dfn-adjusted-parent">adjusted parents</dfn>, or nodes that appear as parents <a href="#dfn-as-rendered">as rendered</a>. The <dfn id="dfn-parent-calculation-algorithm">parent calculation algorithm</dfn> is used to determine the <a href="#dfn-adjusted-parent">adjusted parent</a> of any given node and create the list of ancestors for event dispatch. This algorithm <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>NODE</var>, a DOM node</dd>
<dt>Output</dt>
    <dd><var>PARENT</var>, a DOM node's <a href="#dfn-adjusted-parent">adjusted parent</a></dd>
</dl>
<ol>
    <li>If <var>NODE</var> is a <a href="#dfn-shadow-root">shadow root</a>:
    <ol>
        <li>If <var>NODE</var> is currently <a href="#dfn-assigned">assigned</a> to a <a href="#dfn-shadow-insertion-point">shadow insertion point</a>:
        <ol>
            <li>Let the <var>PARENT</var> be the <a href="#dfn-shadow-insertion-point">shadow insertion point</a> to which <var>NODE</var> is <a href="#dfn-assigned">assigned</a> to</li>
        </ol></li>
        <li>Otherwise, let the <var>PARENT</var> be the <a href="#dfn-shadow-host">shadow host</a> of the <var>NODE</var>
    </li></ol></li>
    <li>If <var>NODE</var> is currently <a href="#dfn-distribution">distributed</a> to an <a href="#dfn-insertion-point">insertion point</a> in a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, let the <var>PARENT</var> be the <a href="#dfn-insertion-point">insertion point</a> to which the <var>NODE</var> is <a href="#dfn-distribution">distributed</a> to</li>
    <li>Otherwise, let <var>PARENT</var> be the node's parent node.</li>
</ol>
</div>

<h3 id="event-retargeting"><span class="section">6.1</span> Event Retargeting</h3>

<p>In the cases where events cross the <a href="#dfn-shadow-boundary">shadow boundaries</a>, the event's information about the target of the event is adjusted in order to maintain <a href="#dfn-upper-boundary-encapsulation">upper boundary encapsulation</a>. Event <dfn id="dfn-retargeting">retargeting</dfn> is a process of computing relative targets for each ancestor of the node at which the event is dispatched. A <dfn id="dfn-relative-target">relative target</dfn> is a DOM node that most accurately represents the target of a dispatched event at a given ancestor while maintaining the <a href="#dfn-upper-boundary-encapsulation">upper boundary encapsulation</a>.

</p><p>The <dfn id="dfn-retargeting-algorithm">retargeting algorithm</dfn> is used to determine relative targets, and it <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>NODE</var>, a DOM node</dd>
<dt>Output</dt>
    <dd><var>TARGETS</var>, a list of tuples, each containing <var>NODE</var>'s ancestor and its relative target</dd>
</dl>
<ol>
    <li>Let <var>STACK</var> be a stack of DOM nodes</li>
    <li>Let <var>ANCESTOR</var> be <var>NODE</var></li>
    <li><dfn id="algo-reatargeting-repeat">Repeat</dfn> while <var>ANCESTOR</var> exists:
    <ol>
        <li>If <var>ANCESTOR</var> is an <a href="#dfn-insertion-point">insertion point</a>, push <var>ANCESTOR</var> into <var>STACK</var></li>
        <li>If <var>STACK</var> is empty, push <var>ANCESTOR</var> into <var>STACK</var></li>
        <li>Let <var>TARGET</var> be the DOM node at the top of <var>STACK</var></li>
        <li>Add (<var>TARGET</var>, <var>ANCESTOR</var>) tuple to <var>TARGETS</var></li>
        <li>If <var>ANCESTOR</var> is a <a href="#dfn-shadow-root">shadow root</a>:
        <ol>
            <li>Pop <var>STACK</var>, if <var>STACK</var> is not empty</li>
        </ol></li>
        <li>Set <var>ANCESTOR</var> to be the result of <a href="#dfn-parent-calculation-algorithm">parent calculation algorithm</a>, given <var>ANCESTOR</var> as input</li>
    </ol></li>
</ol>
</div>

<p>The retargeting process <strong>must</strong> occur prior to dispatch of an event.</p>

<h3 id="retargeting-related-target"><span class="section">6.2</span> Retargeting <code>relatedTarget</code></h3>

<p>Some events have a <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> property, which holds a node that's not the event's target, but is related to the event.</p>

<p>For instance, a <code>mouseover</code> event's <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> may hold the node from which the mouse has moved to event's <code>target</code>. In the case where <code>relatedTarget</code> is in a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, the conforming UAs <strong>must</strong> not leak its actual value outside of this subtree. In cases where both <code>relatedTarget</code> and <code>target</code> are part of the same <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, the conforming UAs <strong>must</strong> <em>stop</em> events at the <a href="#dfn-shadow-boundary">shadow boundary</a> to avoid the appearance of spurious <code>mouseover</code> and <code>mouseout</code> events firing from the same node.</p>

<p>Thus, if an event has a <code>relatedTarget</code>, its value and extent of event dispatch <strong>must</strong> be adjusted. In general:</p>
<ol>
    <li>For a given DOM node, the <code>relatedTarget</code> <strong>must</strong> be changed to its ancestor (or self) that is in the same <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> as the node</li>
    <li>Event listeners <strong>must not</strong> be invoked on a DOM node for which the <code>target</code> and <code>relatedTarget</code> are the same.</li>
</ol>

<p>The <dfn id="dfn-related-target-algorithm">related target resolution</dfn> algorithm <strong>must</strong> be used to determine the value of the <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> property and <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>NODE</var>, the DOM node on which event listeners would be invoked</dd>
    <dd><var>RELATED</var>, the related target for the event</dd>
<dt>Output</dt>
    <dd><var>ADJUSTED</var>, the <dfn id="dfn-adjusted-related-target">adjusted related target</dfn> for <var>NODE</var></dd>
</dl>
<ol>
    <li>Let <var>TARGET</var> be <var>NODE</var></li>
    <li>Let <var>ADJUSTED</var> be <strong>undefined</strong></li>
    <li><dfn id="algo-target-repeat">Repeat</dfn> while <var>TARGET</var> exists:
    <ol>
        <li>Let <var>STACK</var> be an empty stack of DOM nodes</li>
        <li>Let <var>ANCESTOR</var> be <var>RELATED</var></li>
        <li>Let <var>LAST</var> be <strong>undefined</strong></li>
        <li><dfn id="algo-ancestor-repeat">Repeat</dfn> while <var>ANCESTOR</var> exists:
        <ol>
            <li>If <var>STACK</var> is empty, push <var>ANCESTOR</var> into <var>STACK</var></li>
            <li>Otherwise, if <var>ANCESTOR</var> is an <a href="#dfn-insertion-point">insertion point</a>:
            <ol>
                <li>If <var>LAST</var> is <a href="#dfn-distribution">distributed</a> or assigned into <var>ANCESTOR</var>:
                <ol>
                    <li>Let <var>HEAD</var> be the DOM node at the top of the <var>STACK</var></li>
                    <li>Push <var>HEAD</var> into <var>STACK</var></li>
                </ol></li>
            </ol></li>
            <li>If <var>ANCESTOR</var> and <var>TARGET</var> are in the same subtree:
            <ol>
                <li>Let <var>ADJUSTED</var> be the DOM node at the top of the stack</li>
                <li><strong>Stop.</strong></li>
            </ol></li>
            <li>If <var>ANCESTOR</var> is a <a href="#dfn-shadow-root">shadow root</a>, pop <var>STACK</var></li>
            <li>Let <var>LAST</var> be <var>ANCESTOR</var></li>
            <li>Set <var>ANCESTOR</var> to be the result of <a href="#dfn-parent-calculation-algorithm">parent calculation algorithm</a>, given <var>ANCESTOR</var> as input</li>
        </ol></li>
        <li>If <var>TARGET</var> is a <a href="#dfn-shadow-root">shadow root</a>, let <var>TARGET</var> be the <a href="#dfn-shadow-host">shadow host</a> of <var>TARGET</var></li>
        <li>Otherwise, let <var>TARGET</var> be <var>TARGET</var>'s parent node</li>
    </ol></li>
</ol>
</div>

<h3 id="retargeting-focus-events"><span class="section">6.3</span> Retargeting Focus Events</h3>

<p>The <code>focus</code>, <code>DOMFocusIn</code>, <code>blur</code>, and <code>DOMFocusOut</code> events <strong>must</strong> be treated in the same way as events with a <code>relatedTarget</code>, where the corresponding node that is losing focus as a result of <code>target</code> gaining focus or the node that is gaining focus, and thus causing the blurring of <code>target</code> acts as the related target.</p>

<h3 id="events-that-are-always-stopped"><span class="section">6.4</span> Events that are Always Stopped</h3>

<p>The following events <strong>must</strong> always be stopped at the nearest <a href="#dfn-shadow-boundary">shadow boundary</a>:</p>
<ul>
    <li><code>abort</code></li>
    <li><code>error</code></li>
    <li><code>select</code></li>
    <li><code>change</code></li>
    <li><code>load</code></li>
    <li><code>reset</code></li>
    <li><code>resize</code></li>
    <li><code>scroll</code></li>
    <li><code>selectstart</code></li>
</ul>

<h3 id="event-dispatch"><span class="section">6.5</span> Event Dispatch</h3>

<p>At the time of event dispatch:</p>
<ul>
    <li>The <a href="http://www.w3.org/TR/domcore/#event"><code>Event</code></a> <a href="http://www.w3.org/TR/domcore/#dom-event-target"><code>target</code></a> and <a href="http://www.w3.org/TR/domcore/#dom-event-currenttarget"><code>currentTarget</code></a> attributes <strong>must</strong> return the <a href="#dfn-relative-target">relative target</a> for the node on which event listeners are <a href="http://www.w3.org/TR/domcore/#concept-event-listener-invoke">invoked</a></li>
    <li>The <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-UIEvent"><code>UIEvent</code></a> <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> attribute <strong>must</strong> return the <a href="#dfn-adjusted-related-target">adjusted related target</a></li>
    <li>If the <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> and <a href="http://www.w3.org/TR/domcore/#dom-event-target"><code>target</code></a> are the same for a given node, its the event listeners <strong>must not</strong> be invoked</li>
    <li>When <em>capturing</em>, which entails processing step 3 of the <a href="http://www.w3.org/TR/domcore/#dispatching-events">event dispatch algorithm</a>, the <a href="http://www.w3.org/TR/domcore/#event"><code>Event</code></a> <a href="http://www.w3.org/TR/domcore/#dom-event-eventphase">eventPhase</a> attribute <strong>must</strong> return <a href="http://www.w3.org/TR/domcore/#dom-event-at_target">AT_TARGET</a> <strong>if</strong> the <a href="#dfn-relative-target">relative target</a> is same as the node on which event listeners are <a href="http://www.w3.org/TR/domcore/#concept-event-listener-invoke">invoked</a></li>
    <li>When <em>bubbling</em>, which entails processing step 6 of the <a href="http://www.w3.org/TR/domcore/#dispatching-events">event dispatch algorithm</a>, the event listeners <strong>must not</strong> be <a href="http://www.w3.org/TR/domcore/#concept-event-listener-invoke">invoked</a> on a node <strong>if</strong> it is the same as its <a href="#dfn-relative-target">relative target</a></li>
</ul>

<p>Upon completion of the event dispatch, the <a href="http://www.w3.org/TR/domcore/#event"><code>Event</code></a> object's <a href="http://www.w3.org/TR/domcore/#dom-event-target"><code>target</code></a> and <a href="http://www.w3.org/TR/domcore/#dom-event-currenttarget"><code>currentTarget</code></a> <strong>must</strong> be to the highest ancestor's <a href="#dfn-relative-target">relative target</a>. Since it is possible for a script to hold on to the <code>Event</code> object past the scope of event dispatch, this step is necessary to avoid revealing the nodes in <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>.</p>

<h3 id="event-retargeting-example"><span class="section">6.6</span> Event Retargeting Example</h3>

<p>Suppose we have a user interface for a media controller, represented by this DOM tree, composed of both document and the <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>. In this example, we will assume that selectors are allowed to cross the shadow boundaries and we will use these selectors to identify the elements. Also, we will invent a fictional <code>shadow-root</code> element to demarcate the <a href="#dfn-shadow-boundary">shadow boundaries</a> and represent <a href="#dfn-shadow-root">shadow roots</a>:</p>
<pre><code>
&lt;div id="player"&gt;
    <span class="shadow-boundary">&lt;shadow-root id="player-shadow-root"&gt;</span>
        &lt;div id="controls"&gt;
            &lt;button class="play-button"&gt;PLAY&lt;/button&gt;
            &lt;input type="range" id="timeline"&gt;
                <span class="shadow-boundary">&lt;shadow-root id="timeline-shadow-root"&gt;</span>
                    &lt;div class="slider-thumb" id="timeline-slider-thumb"&gt;&lt;/div&gt;
                <span class="shadow-boundary">&lt;/shadow-root&gt;</span>
            &lt;/input&gt;
            &lt;div class="volume-slider-container"&gt;
                &lt;input type="range" class="volume-slider"&gt;
                    <span class="shadow-boundary">&lt;shadow-root id="volume-shadow-root"&gt;</span>
                        &lt;div class="slider-thumb" id="volume-slider-thumb"&gt;&lt;/div&gt;
                    <span class="shadow-boundary">&lt;/shadow-root&gt;</span>
                &lt;/input&gt;
            &lt;/div&gt;
        &lt;/div&gt;
    <span class="shadow-boundary">&lt;/shadow-root&gt;</span>
&lt;/div&gt;
</code></pre>

<p>Let's have a user position their pointing device over the volume slider's thumb (<code>#volume-slider-thumb</code>), thus triggering a <code>mouseover</code> event on that node. For this event, let's pretend it has no associated <code>relatedTarget</code>.</p>

<p>Just before the event is dispatched, we perform <a href="#dfn-retargeting">retargeting</a>:</p>
<ol>
    <li>Since <code>#volume-slider-thumb</code> is not an <a href="#dfn-insertion-point">insertion point</a>, we push it onto <var>STACK</var>, and add the first tuple to <var>TARGETS</var> as (<code>#volume-slider-thumb</code>, <code>#volume-slider-thumb</code>)</li>
    <li>We then <a href="#dfn-parent-calculation-algorithm">calculate parent</a> as <code>#volume-shadow-root</code> and proceed to second iteration, adding (<code>#volume-slider-thumb</code>, <code>#volume-shadow-root</code>) tuple to <var>TARGETS</var></li>
    <li>Because <code>#volume-shadow-root</code> is a <a href="#dfn-shadow-root">shadow root</a>, we pop <var>STACK</var>, thus emptying it</li>
    <li>Next <a href="#dfn-parent-calculation-algorithm">parent calculation</a> yields <code>#volume-slider</code>, and so we begin the third iteration</li>
    <li>Here, <var>STACK</var> is empty again, so we push <code>#volume-slider</code> into it and add (<code>#volume-slider</code>, <code>#volume-slider</code>) to <var>TARGETS</var></li>
    <li>The <a href="#dfn-parent-calculation-algorithm">parent</a> of <code>#volume-slider</code> is <code>#volume-slider-container</code> not a <a href="#dfn-shadow-root">shadow root</a> and not an <a href="#dfn-insertion-point">insertion point</a>, which dictates that we add (<code>#volume-slider</code>, <code>#volume-slider-container</code>) to <var>TARGETS</var></li>
    <li>Next <a href="#dfn-parent-calculation-algorithm">up</a>, we see <code>#controls</code>, again neither a <a href="#dfn-shadow-root">shadow root</a> nor an <a href="#dfn-insertion-point">insertion point</a>, which means we add (<code>##volume-slider</code>, <code>#controls</code>) to <var>TARGETS</var></li>
    <li>The <a href="#dfn-parent-calculation-algorithm">next ancestor</a> is <code>#player-shadow-root</code>, a <a href="#dfn-shadow-root">shadow root</a>, and thus we add it (<code>#volume-slider</code>, <code>#player-shadow-root</code>) to <var>TARGETS</var>, then pop <var>STACK</var>, emptying it</li>
    <li>Its <a href="#dfn-parent-calculation-algorithm">parent</a> is <code>#player</code>, neither <a href="#dfn-shadow-root">shadow root</a> nor <a href="#dfn-insertion-point">insertion point</a>, and <var>STACK</var> is empty, so we push <code>#player</code> to <var>STACK</var>, then add (<code>#player</code>, <code>#player</code>) to <var>TARGETS</var></li>
    <li>In our example, there are no further <a href="#dfn-parent-calculation-algorithm">parents</a>, causing us to exit the <a href="#algo-reatargeting-repeat">loop</a> and stop.</li>
</ol>

<p>At the end of this process, we should have the following set of ancestors and relative targets:</p>
<table>
<thead>
<tr>
    <th>Ancestor</th>
    <th>Relative Target</th>
</tr>
</thead>
<tbody>
<tr>
    <td><code>#player</code></td>
    <td><code><strong>#player</strong></code></td>
</tr>
<tr>
    <td><code>#player-shadow-root</code></td>
    <td><code>#volume-slider</code></td>
</tr>
<tr>
    <td><code>#controls</code></td>
    <td><code>#volume-slider</code></td>
</tr>
<tr>
    <td><code>#volume-slider-container</code></td>
    <td><code>#volume-slider</code></td>
</tr>
<tr>
    <td><code>#volume-slider</code></td>
    <td><code><strong>#volume-slider</strong></code></td>
</tr>
<tr>
    <td><code>#volume-shadow-root</code></td>
    <td><code>#volume-slider-thumb</code></td>
</tr>
<tr>
    <td><code>#volume-slider-thumb</code></td>
    <td><code><strong>#volume-slider-thumb</strong></code></td>
</tr>
</tbody>
</table>

<p>After we dispatch the <code>mouseover</code> event using these newly computed relative targets, the user decides to move their pointing device over the thumb of the timeline
(<code>#timeline-slider-thumb</code>). This triggers both a <code>mouseout</code> event for the volume slider thumb and the <code>mouseover</code> event for the timeline thumb.</p>

<p>Let's study how the <code>relatedTarget</code> value of the volume thumb's <code>mouseout</code> event is affected. For this event, the <code>relatedTarget</code> is the timeline thumb (<code>#timeline-slider-thumb</code>). Per <a href="#dfn-related-target-algorithm">algorithm</a>:</p>

<ol>
    <li>Starting with <var>NODE</var> as <code>#volume-slider-thumb</code> and <var>RELATED</var> as <code>#timeline-slider-thumb</code>,</li>
    <li>We <a href="#algo-ancestor-repeat">examine</a> ancestors of <var>RELATED</var>:
    <ol>
        <li>First <a href="#dfn-parent-calculation-algorithm">up</a> is <code>#timeline-slider-thumb</code>, and we push it into <var>STACK</var></li>
        <li>Then it's <code>#timeline-shadow-root</code>, a <a href="#dfn-shadow-root">shadow root</a>, so we pop <var>STACK</var>, emptying it</li>
        <li>Next is <code>#timeline</code>, we push it into <var>STACK</var></li>
        <li>Then comes <code>#controls</code> and after it, <code>#player-shadow-root</code>, a <a href="#dfn-shadow-root">shadow root</a>, so we pop <var>STACK</var>, emptying it</li>
        <li>Final ancestor is <code>#player</code>, we push it into <var>STACK</var></li>
    </ol>
    </li><li>Set <var>TARGET</var> to <code>#volume-shadow-root</code></li>
    <li>We again <a href="#algo-ancestor-repeat">examine</a> ancestors of <var>RELATED</var> and notice that it produces the same result as our previous such examination</li>
    <li>We then set <var>TARGET</var> to <code>#volume-slider</code> and</li>
    <li>Repeat <a href="#algo-ancestor-repeat">examination</a> of ancestors once more—and realize that when <var>ANCESTOR</var> value is <code>#timeline</code>, the <var>ANCESTOR</var> and <var>TARGET</var> are in the same tree, and thus</li>
    <li>Return <code>#timeline</code> as the adjusted <code>relatedTarget</code> value.
</li></ol>

<p>Performing this computation with <var>NODE</var> as <code>#player</code> yields the result of both <code>target</code> and <code>relatedTarget</code> being the same value (<code>#player</code>), which means that we do not dispatch the event on this node and its ancestors.</p>

<h2 id="styles"><span class="section">7</span> Styles</h2>

<p>Each <a href="#dfn-shadow-root">shadow root</a> has an associated list of zero or more <a href="http://www.w3.org/TR/cssom/#style-sheet">style sheets</a>, named <dfn id="dfn-shadow-root-style-sheets">shadow root style sheets</dfn>. This is an ordered list that contains all <a href="http://www.w3.org/TR/cssom/#style-sheet">style sheets</a>, associated with the <a href="#dfn-shadow-root">shadow root</a>, in <a href="http://www.w3.org/TR/dom/#concept-tree-order">tree order</a>.</p>

<p>When a <a href="#dfn-shadow-host">shadow host</a> has multiple <a href="#dfn-shadow-root">shadow roots</a>, the <a href="http://www.w3.org/TR/CSS2/cascade.html#cascading-order">sorting order</a> of <a href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rules</a>, defined in <a href="#dfn-shadow-root-style-sheets">shadow roow style sheets</a>, in ascending order of precedence <strong>must</strong> match the order of the <a href="#dfn-tree-stack">tree stack</a>, ending with the <a href="#dfn-youngest-tree">youngest tree</a>.

</p><p>To enforce <a href="#dfn-upper-boundary-encapsulation">upper-boundary encapsulation</a>, <a href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rules</a> declared by the document <strong>must not</strong> apply in a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, unless the <dfn id="dfn-apply-author-styles">apply-author-styles</dfn> flag is set for this subtree. The flag signals that document CSS rules are applicable in the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>.

</p><p>Even when the <a href="#dfn-apply-author-styles">apply-author-styles</a> is set, the <a href="http://www.w3.org/TR/selectors/">selectors</a> still <strong>must not</strong> cross the <a href="#dfn-shadow-boundary">shadow boundary</a> per <a href="#dfn-scoping-constraints">scoping constraints</a>. In other words, with <a href="#dfn-apply-author-styles">apply-author-styles</a> set, the document CSS rules only match wholly inside or outside of the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>.</p>

<p>Conversely, to enforce <a href="#dfn-lower-boundary-encapsulation">lower-boundary encapsulation</a>, <a href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rules</a> declared in a <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a> <strong>must not</strong> apply in the document tree, with two exceptions:</p>
<ol>
    <li>Rules that contain <code>select</code> <a href="http://dev.w3.org/csswg/selectors4/#idref-combinators">reference combinators</a> and match elements in the document tree;</li>
    <li>The <a href="#host-at-rule"><code>@host</code> @-rule</a> that matches a <a href="#dfn-shadow-host">shadow host</a> in a document tree.</li>
</ol>

<p>The <dfn id="dfn-rule-applicability-algorithm">rule applicability algorithm</dfn> is used to determine whether any given rule is applicable to any DOM tree, and it <strong>must</strong> be equivalent to processing the following steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
<dd><var>RULE</var>, a CSS rule whose applicability is being determined</dd>
<dd><var>TREE</var>, the document tree or <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a></dd>
<dt>Output</dt>
<dd>Whether <var>RULE</var> is applicable in <var>TREE</var>.</dd>
</dl>
<ol>
    <li>If <var>RULE</var> is not an <a href="http://www.w3.org/TR/CSS2/cascade.html">author style</a>, the rule <strong>is</strong> applicable in <var>TREE</var>.</li>
    <li>Otherwise, if <var>RULE</var> is either an <a href="#host-at-rule"><code>@host</code> @-rule</a> or contains a <code>select</code>  <a href="http://dev.w3.org/csswg/selectors4/#idref-combinators">reference combinator</a> <em>and</em> <var>RULE</var> is declared in <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>:
    <ol>
        <li>Let <var>BOTTOM</var> the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, with which these <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a> are associated</li>
        <li>If the <a href="#dfn-shadow-host">shadow host</a> of <var>BOTTOM</var> is in <var>TREE</var>, then <var>RULE</var> <strong>is</strong> applicable in <var>TREE</var>.</li>
    </ol></li>
    <li>Otherwise, if <var>TREE</var> is a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>:
    <ol>
        <li>If <var>TREE</var> has <a href="#dfn-apply-author-styles">apply-author-styles</a> flag set and <var>RULE</var> is declared in the document tree, <var>RULE</var> <strong>is</strong> applicable in <var>TREE</var>.</li>
        <li>Otherwise, if <var>RULE</var> is declared in <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>:
        <ol>
            <li>Let <var>TOP</var> the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, with which these <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a> are associated</li>
            <li>If <var>TOP</var> is <var>TREE</var>, then <var>RULE</var> <strong>is</strong> applicable in <var>TREE</var>.</li>
            <li>Otherwise, if <var>TREE</var> has <a href="#dfn-apply-author-styles">apply-author-styles</a> flag set and if each <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> that both <a href="#dfn-enclosed-subtree">encloses</a> <var>TREE</var> and is <a href="#dfn-enclosed-subtree">enclosed</a> by <var>TOP</var> has <a href="#dfn-apply-author-styles">apply-author-styles</a> flag set, then <var>RULE</var> <strong>is</strong> applicable in <var>TREE</var>.</li>
        </ol></li>
        <li>Otherwise, <var>RULE</var> <strong>is not</strong> applicable in <var>TREE</var>.</li>
    </ol></li>
    <li>Otherwise, if <var>TREE</var> is a document tree and <var>RULE</var> is declared in <var>TREE</var>, the rule <strong>is</strong> applicable in <var>TREE</var>.</li>
    <li>Otherwise, <var>RULE</var> <strong>is not</strong> applicable in <var>TREE</var>.</li>
</ol>
</div>

<p>In a document that contains <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>, the CSS properties <strong>must</strong> be inherited from parent nodes, produced using <a href="#dfn-parent-calculation-algorithm">parent calculation algorithm</a>. This requirement has the following effects:</p>
<ul>
    <li>the styles of the <a href="#dfn-shadow-host">shadow host</a> are inherited by the children of the <a href="#dfn-shadow-root">shadow root</a></li>
    <li>the styles of the <a href="#dfn-insertion-point">insertion point</a> node are inherited by those child nodes of the <a href="#dfn-shadow-host">shadow host</a> that are <a href="#dfn-assigned">assigned</a> to this <a href="#dfn-insertion-point">insertion point</a></li>
    <li>the styles of the <a href="#dfn-shadow-insertion-point">shadow insertion point</a> node are inherited by the child nodes of the <a href="#dfn-shadow-root">shadow root</a> of the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, <a href="#dfn-distribution">distributed</a> to this <a href="#dfn-shadow-insertion-point">shadow insertion point</a></li>
</ul>

<p>If the <dfn id="dfn-reset-style-inheritance">reset-style-inheritance</dfn> flag is set for a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, all <a href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#inheritance">inheritable</a> CSS properties <strong>must</strong> behave as if they were explicitly set to the <a href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#initial0">initial value</a> at the upper boundary of the subtree.</p>

<p>If the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag is set for an <a href="#dfn-insertion-point">insertion point</a> in a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, all <a href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#inheritance">inheritable</a> CSS properties <strong>must</strong> behave as if they were explicitly set to the <a href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#initial0">initial value</a> at the lower boundary of the subtree.</p>

<h3 id="css-variables"><span class="section">7.1</span> CSS Variables</h3>

<p>The <a href="#dfn-shadow-host">shadow host</a> styles being inherited by the children of the <a href="#dfn-shadow-root">shadow root</a> <strong>must</strong> also apply to <a href="http://dev.w3.org/csswg/css-variables/">CSS Variables</a>. This provides a way for document DOM tree styles to send signals into the <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>, and for the <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a> to receive these signals with the use of the <a href="http://dev.w3.org/csswg/css-variables/#using-variables"><code>var()</code></a> function.</p>

<h3 id="text-decoration-property"><span class="section">7.2</span> <code>text-decoration</code> Property</h3>

<p>The text decorations, specified by the <a href="http://www.w3.org/TR/CSS2/text.html#lining-striking-props"><code>text-decoration</code></a> property <strong>must not</strong> be propagated from <a href="#dfn-shadow-host">shadow hosts</a> to <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>.</p>

<h3 id="host-at-rule"><span class="section">7.3</span> <code>@host</code> @-rule</h3>

<p>Within styles, specified in <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>, the author may use a <code>@host</code> @-rule. The syntax of this rule is defined as this addition to <a href="http://www.w3.org/TR/CSS21/grammar.html">CSS Grammar</a>:</p>

<p>The following production is added to the <a href="http://www.w3.org/TR/CSS21/grammar.html#grammar">grammar</a>:</p>

<pre><code>
host
    : HOST_SYM S* '{' S* ruleset* '}' S*
    ;
</code></pre>

<p>The following rule is added to the <a href="http://www.w3.org/TR/CSS21/grammar.html#scanner">tokenizer</a>:</p>

<pre><code>
@{H}{O}{S}{T}        {return HOST_SYM;}
</code></pre>

<p>The <a href="http://www.w3.org/TR/CSS21/syndata.html#x19">declarations</a> of the rules in a <code>@host</code> @-rule <strong>must</strong> only be matched against the <a href="#dfn-shadow-host">shadow host</a> of the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> in which the style is specified, but only if this <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> is <a href="#dfn-rendering">rendered</a>. When the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> is not <a href="#dfn-rendering">rendered</a> (when it's an older tree that is not assigned to a <a href="#dfn-shadow-insertion-point">shadow insertion point</a>), the <a href="http://www.w3.org/TR/CSS21/syndata.html#x19">declarations</a> <strong>must not</strong> be applied.</p>

<p>When a rule in <a href="#host-at-rule"><code>@host</code> @-rule</a> matches an element, it <strong>must</strong> have higher <a href="http://www.w3.org/TR/CSS2/cascade.html#specificity">specificity</a> than any <a href="http://www.w3.org/TR/selectors/">selector</a>, but lower <a href="http://www.w3.org/TR/CSS2/cascade.html#specificity">specificity</a> than <a href="http://www.w3.org/TR/CSS21/syndata.html#x19">declarations</a> from a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#the-style-attribute"><code>style</code></a> attribute.</p>


<section class="mechanics">

<h2 id="user-interaction"><span class="section">8</span> User Interaction</h2>

<h3 id="ranges-and-selection"><span class="section">8.1</span> Ranges and Selections</h3>

<p>Since a DOM node in a document tree and a DOM node in a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> never have the same <a href="http://www.w3.org/TR/domcore/#concept-tree-root">root</a>, there may never exist a valid <a href="http://www.w3.org/TR/domcore/#range">DOM range</a> that spans either both a document tree and a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>, or multiple <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>.</p>

<p>Accordingly, <a href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#concept-selection">selections</a> may only exist within one tree, because they are defined by a single <a href="http://www.w3.org/TR/domcore/#range">range</a>. To maintain <a href="#dfn-upper-boundary-encapsulation">upper boundary encapsulation</a>, the selection, returned by the <a href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#dom-window-getselection"><code>window.getSelection()</code></a> method <strong>must</strong> never return a selection within a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>.</p>

<p>The <code>getSelection()</code> method of the <a href="#dfn-shadow-root">shadow root</a> object <strong>must</strong> return the current <a href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#concept-selection">selection</a> in this <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>.</p>

<h3 id="focus-navigation"><span class="section">8.2</span> Focus Navigation</h3>

<p><a href="#dfn-shadow-dom-subtree">Shadow DOM subtrees</a> participate in <a href="http://www.w3.org/TR/css3-ui/#keyboard">sequential</a> or <a href="http://www.w3.org/TR/css3-ui/#keyboard">directional</a> focus navigation as part of the document tree. The <a href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a> within a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> <strong>must</strong> be computed as a list of <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#focusable">focusable</a> elements in <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#tree-order">tree order</a> <a href="#dfn-as-rendered">as-rendered</a>, with the exception of any elements, <a href="#dfn-distribution">distributed</a> its <a href="#dfn-insertion-point">insertion points</a>, and is called <dfn id="dfn-shadow-dom-navigation-order">shadow DOM navigation order</dfn>.</p>

<p>For <a href="http://www.w3.org/TR/css3-ui/#keyboard">sequential focus navigation</a>, the <a href="#dfn-shadow-dom-navigation-order">shadow DOM navigation order</a> sequence <strong>must</strong> be inserted into the document <a href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a>:</p>
<ol>
    <li>immediately after the <a href="#dfn-shadow-host">shadow host</a>, if the shadow host is <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#focusable">focusable</a>; or</li>
    <li>in place of the <a href="#dfn-shadow-host">shadow host</a> as if the shadow host were assigned the value of <a href="http://www.w3.org/TR/css3-ui/#keyboard"><code>auto</code></a> for determining its position.</li>
</ol>

<p>For <a href="http://www.w3.org/TR/css3-ui/#keyboard">directional focus navigation</a>, it is up to the user agent to integrate the <a href="#dfn-shadow-dom-navigation-order">shadow DOM navigation order</a> into the document <a href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a>.</p>

<h3 id="active-element"><span class="section">8.3</span> Active Element</h3>

<p>To maintain <a href="#dfn-upper-boundary-encapsulation">upper-boundary encapsulation</a>, the value of the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#document">Document</a> object's focus API property <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#dom-document-activeelement">activeElement</a> <strong>must</strong> be adjusted. To prevent loss of information when adjusting this value, each <a href="#dfn-shadow-root">shadow root</a> <strong>must</strong> also have an <code>activeElement</code> property to store the value of the focused element in the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>.</p>

<p>The <dfn id="active-element-adjustment-algorithm">active element adjustment algorithm</dfn> is used to determine the values of the respective <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#dom-document-activeelement">activeElement</a> properties, and it <strong>must</strong> be equivalent to processing the following steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>ELEMENT</var>, the focused element</dd>
<dt>Output</dt>
    <dd>Adjusted values of <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#dom-document-activeelement">activeElement</a> properties.</dd>
</dl>
<ol>
    <li>Run the <a href="#dfn-retargeting-algorithm">retargeting algorithm</a> with <var>ELEMENT</var> as input</li>
    <li>For each <var>TUPLE</var> in the resulting list of tuples:
    <ol>
        <li>Let <var>ADJUSTED</var> be the first value of the <var>TUPLE</var></li>
        <li>Let <var>NODE</var> be the second value of the <var>TUPLE</var></li>
        <li>If <var>NODE</var> is a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#document">Document</a> or a <a href="#dfn-shadow-root">shadow root</a>, set the value of the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#dom-document-activeelement">activeElement</a> to <var>ADJUSTED</var>.</li>
    </ol>
    </li>
</ol>
</div>

<h3 id="editing"><span class="section">8.4</span> Editing</h3>

<p>The value of the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#attr-contenteditable"><code>contenteditable</code></a> attribute <strong>must not</strong> propagate from <a href="#dfn-shadow-host">shadow host</a> to its <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>.</p>

<h3 id="assistive-technology"><span class="section">8.5</span> Assistive Technology</h3>

<p>User agents with assistive technology traverse the document tree <a href="#dfn-as-rendered">as rendered</a>, and thus enable full use of of <a href="http://www.w3.org/WAI/PF/aria/">WAI-ARIA</a> semantics in the <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>.</p>

<h2 id="html-elements"><span class="section">9</span> HTML Elements in Shadow DOM Subtrees</h2>

<p>Comparatively, a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> can be seen as somewhere between <em>just a DOM subtree in a document</em> and a <a href="http://www.w3.org/TR/domcore/#interface-documentfragment">document fragment</a>. Since it is rendered, a shadow DOM subtree aims to retain the traits of a typical DOM subtree in a document. At the same time, it is an encapsulation abstraction, so it has to avoid affecting the document DOM tree. Thus, the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> <strong>must</strong> behave <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">as specified</a> in the <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>, with a few exceptions.</p>

<h3 id="inert-html-elements"><span class="section">9.1</span> Inert HTML Elements</h3>

<p>A subset of <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> <strong>must</strong> behave as <dfn id="dfn-inert">inert</dfn>, or not part of the document tree. This is consistent how the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> would behave in a <a href="http://www.w3.org/TR/domcore/#interface-documentfragment">document fragment</a>. These elements are:</p>
<ul>
    <li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-base-element"><code>base</code></a></li>
    <li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-link-element"><code>link</code></a></li>
</ul>

<p>All other <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> in the <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a> <strong>must</strong> behave as if they were part of the document tree, with the <a href="#dfn-scoping-constraints">scoping constraints</a> of their respective subtrees applied.</p>

<h3 id="html-forms"><span class="section">9.2</span> HTML Forms</h3>

<p>The <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#forms">forms</a> in HTML are scoped at the document level. That is, all <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#the-form-element"><code>form</code></a> elements and <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#form-associated-element">form-associated elements</a> are accessible using the document <a href="http://www.w3.org/TR/domcore/#interface-document">DOM object</a>'s <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-tree-accessors">tree accessors</a>. Per <a href="#dfn-scoping-constraints">scoping constraints</a>, this <strong>must</strong> exclude elements in the <a href="#dfn-shadow-dom-subtree">shadow DOM subtrees</a>.</p>

<p>Instead, each <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> <strong>must</strong> scope its <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#the-form-element"><code>form</code></a> elements and <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#form-associated-element">form-associated elements</a>. Because the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#the-form-element"><code>form</code></a>'s <a href="http://www.w3.org/TR/domcore/#dom-node-ownerdocument"><code>ownerDocument</code></a> is the <a href="#dfn-shadow-host">shadow host</a>'s document, the form submission <strong>must</strong> continue to work <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#form-submission">as specified</a>.</p>

<h2 id="html-elements-and-their-shadow-dom-subtrees"><span class="section">10</span> HTML Elements and Their Shadow DOM Subtrees</h2>

<p>Per <a href="http://www.whatwg.org/specs/web-apps/current-work/">specification</a>, some <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> are designed to either not render their contents or have special requirements in regard to contents rendering. In order to reconcile these differences in rendering behavior with the shadow DOM <a href="#dfn-tree-composition">tree composition</a>, all <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> <strong>must</strong> have an <a href="#dfn-processing-equivalence">equivalent</a> of a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> that is created and populated at the time of element instantiation. It is up to a user agent to define the content of these subtrees. However, all conforming user agents <strong>must</strong> satisfy the following requirements:</p>

<table>
<thead>
    <tr>
        <th style="width: 30%">HTML Element</th>
        <th>Shadow DOM Subtree Requirements</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/embedded-content-1.html#the-img-element"><code>img</code></a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-iframe-element.html#the-iframe-element"><code>iframe</code></a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-iframe-element.html#the-embed-element"><code>embed</code></a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-iframe-element.html#the-object-element"><code>object</code></a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-video-element.html#the-video-element"><code>video</code></a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-video-element.html#the-audio-element"><code>audio</code></a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#the-canvas-element"><code>canvas</code></a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-map-element.html#the-map-element"><code>map</code></a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-input-element.html#the-input-element"><code>input</code></a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-button-element.html#the-textarea-element"><code>textarea</code></a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-button-element.html#the-progress-element"><code>progress</code></a>, <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-button-element.html#the-meter-element"><code>meter</code></a></td>
        <td>If the element that can have <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#fallback-content">fallback content</a>, contains one <a href="#dfn-insertion-point">insertion point</a>. The <a href="#dfn-matching-criteria">matching criteria</a> value is <a href="http://www.w3.org/TR/css3-selectors/#universal-selector">universal selector</a> only when the element needs to show <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#fallback-content">fallback content</a>. Otherwise, contains no <a href="#dfn-insertion-point">insertion points</a> or an <a href="#dfn-insertion-point">insertion points</a> that matches nothing.</td>
    </tr>
    <tr>
        <td><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#the-fieldset-element"><code>fieldset</code></a></td>
        <td>Contains two <a href="#dfn-insertion-point">insertion points</a> with the following <a href="#dfn-matching-criteria">matching criteria</a>:
        <ol>
            <li><code>legend:first-of-type</code></li>
            <li><a href="http://www.w3.org/TR/css3-selectors/#universal-selector">universal selector</a></li>
        </ol>
        </td>
    </tr>
    <tr>
        <td><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/interactive-elements.html#the-details-element"><code>details</code></a></td>
        <td>Contains two <a href="#dfn-insertion-point">insertion points</a> with the following <a href="#dfn-matching-criteria">matching criteria</a>:
        <ol>
            <li><code>summary:first-of-type</code></li>
            <li><a href="http://www.w3.org/TR/css3-selectors/#universal-selector">universal selector</a></li>
        </ol>
        </td>
    </tr>
    <tr>
        <td>All other elements</td>
        <td>Contains one <a href="#dfn-insertion-point">insertion point</a> with the <a href="http://www.w3.org/TR/css3-selectors/#universal-selector">universal selector</a> as the <a href="#dfn-matching-criteria">matching criteria</a></td>
    </tr>
</tbody>
</table>

<h2 id="elements-and-dom-objects"><span class="section">11</span> Elements and DOM Objects</h2>

<h3 id="shadow-root-object"><span class="section">11.1</span> <code>ShadowRoot</code> Object</h3>

<p>The <code>ShadowRoot</code> object represents the <a href="#dfn-shadow-root">shadow root</a>.</p>
    
<pre><code>
[Constructor(in <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#htmlelement">HTMLElement</a> host) raises (DOMException)]
interface <dfn id="api-shadow-root">ShadowRoot</dfn> : <a href="http://www.w3.org/TR/domcore/#interface-documentfragment">DocumentFragment</a> {
    <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#htmlelement">HTMLElement</a> <a href="#api-shadow-root-get-element-by-id">getElementById</a>(in DOMString elementId);
    <a href="http://www.w3.org/TR/domcore/#nodelist">NodeList</a> <a href="#api-shadow-root-get-elements-by-class-name">getElementsByClassName</a>(in DOMString tagName);
    <a href="http://www.w3.org/TR/domcore/#nodelist">NodeList</a> <a href="#api-shadow-root-get-elements-by-tag-name">getElementsByTagName</a>(in DOMString className);
    <a href="http://www.w3.org/TR/domcore/#nodelist">NodeList</a> <a href="#api-shadow-root-get-elements-by-tag-name-ns">getElementsByTagNameNS</a>(DOMString namespace, DOMString localName);
    <a href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#selection">Selection</a> <a href="#api-shadow-root-selection">getSelection</a>();
    <a href="http://www.w3.org/TR/cssom/#the-cssstylesheet-interface">CSSStyleSheet</a> <a href="#api-shadow-root-add-style-sheet">addStyleSheet</a>(HTMLElement element) raises (DOMException);
    <a href="http://www.w3.org/TR/cssom/#the-cssstylesheet-interface">CSSStyleSheet</a> <a href="#api-shadow-root-remove-style-sheet">removeStyleSheet</a>(<a href="http://www.w3.org/TR/cssom/#the-cssstylesheet-interface">CSSStyleSheet</a> styleSheet) raises (DOMException);
    attribute bool <a href="#api-shadow-root-apply-author-styles">applyAuthorStyles</a>;
    attribute bool <a href="#api-shadow-root-reset-style-inheritance">resetStyleInheritance</a>;
    readonly attribute Element <a href="#api-shadow-root-active-element">activeElement</a>;
    attribute DOMString <a href="#api-shadow-root-inner-html">innerHTML</a>;
    readonly attribute <a href="http://www.w3.org/TR/cssom/#the-stylesheet-interface">StyleSheetList</a> <a href="#api-shadow-root-style-sheets">styleSheets</a>;
}
</code></pre>

<h4 id="shadow-root-attributes"><span class="section">11.1.1</span> <code>ShadowRoot</code> Attributes</h4>

<dl>
<dt id="api-shadow-root-apply-author-styles"><code>applyAuthorStyles</code> of type <code>bool</code></dt>
<dd>Represents the <a href="#dfn-apply-author-styles">apply-author-styles</a> flag and indicates whether or not the rules in <a href="http://www.w3.org/TR/CSS2/cascade.html">author styles</a> associated with the element's document apply to the shadow DOM subtree. If <code>false</code> (default value), the author styles <strong>are not</strong> applied to the shadow DOM subtree. If <code>true</code>, the author styles <strong>are</strong> applied.</dd>
<dd>On getting, the attribute <strong>must</strong> return the current value of the <a href="#dfn-apply-author-styles">apply-author-styles</a> flag for the <a href="#dfn-shadow-host">shadow host</a>'s subtree.</dd>
<dd>On setting, the attribute <strong>must</strong> set the value of the <a href="#dfn-apply-author-styles">apply-author-styles</a> flag for the <a href="#dfn-shadow-host">shadow host</a>'s subtree to specified value.</dd>
<dt id="api-shadow-root-reset-style-inheritance"><code>resetStyleInheritance</code> of type <code>bool</code></dt>
<dd>Represents the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag and indicates whether or not the inheritable CSS properties are set to the initial value at the shadow boundary. If <code>false</code> (default value), the properties continue to inherit. If <code>true</code>, the properties are set to initial value.</dd>
<dd>On getting, the attribute <strong>must</strong> return the current value of the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag for the <a href="#dfn-shadow-host">shadow host</a>'s subtree.</dd>
<dd>On setting, the attribute <strong>must</strong> set the value of the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag for the <a href="#dfn-shadow-host">shadow host</a>'s subtree to specified value.</dd>
<dt id="api-shadow-root-active-element"><code>activeElement</code> of type <code>Element</code>, readonly</dt>
<dd>Represents the currently focused element in the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>.</dd>
<dd>On getting, the attribute <strong>must</strong> return the currently focused element in the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a> or <code>null</code>, if there is none.</dd>
<dt id="api-shadow-root-inner-html"><code>innerHTML</code> of type <code>DOMString</code></dt>
<dd>represents the markup of <a href="#api-shadow-root"><code>ShadowRoot</code></a>'s contents.</dd>
<dd>On getting, the attribute <strong>must</strong> return the result of running the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-end.html#html-fragment-serialization-algorithm">HTML fragment serialization algorithm</a> with the <a href="http://html5.org/specs/dom-parsing.html#context-object">context object</a> as <a href="#dfn-shadow-host"><code>shadow host</code></a>.</dd>
<dd>On setting, these steps <strong>must</strong> be run:
<ol>
    <li>Let <var>FRAGMENT</var> be the result of invoking the <a href="http://html5.org/specs/dom-parsing.html#concept-parse-fragment">fragment parsing algorithm</a> with the new value as <var>MARKUP</var>, and the <a href="http://html5.org/specs/dom-parsing.html#context-object">context object</a> as <a href="#dfn-shadow-host"><code>shadow host</code></a></li>
    <li><a href="#dfn-shadow-host"></a><a href="http://www.w3.org/TR/dom/#concept-node-replace-all">Replace all</a> with <var>FRAGMENT</var> within the <a href="#dfn-shadow-root">shadow root</a>.</li>
</ol></dd>
<dt id="api-shadow-root-style-sheets"><code>styleSheets</code> of type <code>StyleSheetList</code>, readonly</dt>
<dd>Represents the <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>.</dd>
<dd>On getting, the attribute <strong>must</strong> return a <code>StyleSheetList</code> sequence containing the <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>.
</dd>
</dl>

<p>The <a href="http://www.w3.org/TR/domcore/#dom-node-nodetype"><code>nodeType</code></a> attribute of a <a href="#api-shadow-root"><code>ShadowRoot</code></a> instance <strong>must</strong> return <a href="http://www.w3.org/TR/domcore/#dom-node-document_fragment_node"><code>DOCUMENT_FRAGMENT_NODE</code></a>. Accordingly, the <a href="http://www.w3.org/TR/domcore/#dom-node-nodename"><code>nodeName</code></a> attribute of a <a href="#api-shadow-root"><code>ShadowRoot</code></a> instance <strong>must</strong> return <code>"#document-fragment"</code>.</p>

<h4 id="shadow-root-methods"><span class="section">11.1.2</span> <code>ShadowRoot</code> Methods</h4>

<dl>
<dt><code>constructor</code></dt>
<dd>
    <table>
        <thead>
            <tr>
                <th>Parameter</th>
                <th>Type</th>
                <th>Nullable</th>
                <th>Optional</th>
                <th>Description</th>
            </tr>
        </thead>
            <tbody><tr>
                <td><dfn id="api-shadow-root-constructor-element"><code>element</code></dfn></td>
                <td><a href="http://www.w3.org/TR/domcore/#element"><code>Element</code></a></td>
                <td>No</td>
                <td>No</td>
                <td>Element that will be the <a href="#dfn-shadow-host">shadow host</a> of the newly created <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>.</td>
            </tr>
        </tbody><tbody>
        </tbody>
    </table>
    <div>
        <em>Exceptions:</em>
        <dl>
            <dt><a href="http://www.w3.org/TR/domcore/#dom-domexception-hierarchy_request_err"><code>HIERARCHY_REQUEST_ERR</code></a></dt>
            <dd>This exception <strong>must</strong> be thrown when the <code>element</code> parameter is not a valid <a href="http://www.w3.org/TR/domcore/#element"><code>Element</code></a>.
        </dd></dl>
    </div>
    <p>When invoked, the <code>ShadowRoot()</code> constructor <strong>must</strong> run these steps:</p>
    <ol>
        <li>Create a new instance of the <code>ShadowRoot</code> object</li>
        <li>Establish element, supplied as <code>element</code> argument as the <a href="#dfn-shadow-host">shadow host</a> for the <code>ShadowRoot</code> object</li>
        <li>Return <code>ShadowRoot</code> object</li>
    </ol>
</dd>
<dt id="api-shadow-root-get-element-by-id"><code>getElementById</code></dt>
<dd><strong>Must</strong> behave exactly like <a href="http://www.w3.org/TR/domcore/#dom-document-getelementbyid">document.getElementById</a>, except <a href="#dfn-scoping-constraints">scoped</a> to the shadow DOM subtree.</dd>
<dt id="api-shadow-root-get-elements-by-class-name"><code>getElementsByClassName</code></dt>
<dd><strong>Must</strong> behave exactly like <a href="http://www.w3.org/TR/domcore/#dom-document-getelementsbyclassname">document.getElementsByClassName</a>, except <a href="#dfn-scoping-constraints">scoped</a> to the shadow DOM subtree.</dd>
<dt id="api-shadow-root-get-elements-by-tag-name"><code>getElementsByTagName</code></dt>
<dd><strong>Must</strong> behave exactly like <a href="http://www.w3.org/TR/domcore/#dom-document-getelementsbytagname">document.getElementsByTagName</a>, except <a href="#dfn-scoping-constraints">scoped</a> to the shadow DOM subtree.</dd>
<dt id="api-shadow-root-get-elements-by-tag-name-ns"><code>getElementsByTagNameNS</code></dt>
<dd><strong>Must</strong> behave exactly like <a href="http://www.w3.org/TR/domcore/#dom-document-getelementsbytagnamens">document.getElementsByTagNameNS</a>, except <a href="#dfn-scoping-constraints">scoped</a> to the shadow DOM subtree.</dd>
<dt id="api-shadow-root-selection"><code>getSelection</code></dt><dt>
</dt><dd>Returns the current selection in the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>.</dd>
<dd>When invoked, it <strong>must</strong> return <a href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#concept-selection">selection</a> in <a href="#dfn-shadow-host">shadow host</a>'s subtree.</dd>
<dt id="api-shadow-root-add-style-sheet"><code>addStyleSheet</code></dt>
<dd>Adds a new <a href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a> to <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>.</dd>
<dd>When invoked, the method <strong>must</strong> run the following steps:
<ol>
    <li>If the parameter is an <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#htmllinkelement">HTMLLinkElement</a>:
    <ol>
        <li>Follow <a href="http://www.w3.org/TR/cssom/#requirements-on-user-agents-implementing-the-http-link-header">requirements</a> for implementing the HTTP <code>link</code> header with the exception that the newly created style sheet <strong>must</strong> be appended to the <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>, not <a href="http://www.w3.org/TR/cssom/#document-style-sheets">document style sheets</a></li>
        <li>Return the newly created <a href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a> object.</li>
    </ol></li>
    <li>If the parameter is an <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#htmlstyleelement">HTMLStyleElement</a>:
    <ol>
        <li><a href="http://www.w3.org/TR/cssom/#create-a-style-sheet">Create a style sheet</a> with the following properties and the exception that the newly created style sheet <strong>must</strong> be appended to the <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>, not <a href="http://www.w3.org/TR/cssom/#document-style-sheets">document style sheets</a>:
        <dl>
            <dt><a href="http://www.w3.org/TR/cssom/#style-sheet-location">style sheet location</a></dt>
            <dd>null</dd>
            <dt><a href="http://www.w3.org/TR/cssom/#style-sheet-owner-node">style sheet owner node</a></dt>
            <dd>null</dd>
            <dt><a href="http://www.w3.org/TR/cssom/#style-sheet-parent">style sheet parent</a></dt>
            <dd>null</dd>
            <dt><a href="http://www.w3.org/TR/cssom/#style-sheet-owner-css-rule">style sheet owner CSS rule</a></dt>
            <dd>null</dd>
            <dt><a href="http://www.w3.org/TR/cssom/#style-sheet-owner-css-rule">style sheet owner CSS rule</a></dt>
            <dd>null</dd>
            <dt><a href="http://www.w3.org/TR/cssom/#style-sheet-media">style sheet media</a></dt>
            <dd>null</dd>
            <dt><a href="http://www.w3.org/TR/cssom/#style-sheet-title">style sheet title</a></dt>
            <dd>null</dd>
            <dt><a href="http://www.w3.org/TR/cssom/#style-sheet-alternate-flag">style sheet alternate flag</a></dt>
            <dd>false</dd>
        </dl></li>
        <li>Return the newly created <a href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a> object.</li>
    </ol>
    </li><li>Otherwise, throw a <a href="http://www.w3.org/TR/domcore/#typemismatcherror"><code>TypeMismatchError</code></a> exception.</li>
</ol></dd>
<dt id="api-shadow-root-remove-style-sheet"><code>removeStyleSheet</code></dt>
<dd>Removes a <a href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a>, added with <a href="#api-shadow-root-add-style-sheet"><code>addStyleSheet</code></a>.</dd>
<dd>When invoked, the method <strong>must</strong> run these steps:
<ol>
    <li>If the <a href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a>, represented by the method parameter exists in the <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a> and was added with <a href="#api-shadow-root-add-style-sheet"><code>addStyleSheet</code></a>:
    <ol>
        <li>Remove the <a href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a> from <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>.</li>
        <li>Return the removed <a href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a> instance.</li>
    </ol></li>
    <li>Otherwise, throw a <a href="http://www.w3.org/TR/domcore/#nomodificationallowederror"><code>NoModificationAllowedError</code></a> exception.</li>
</ol></dd>
</dl>

<p>Invoking the <a href="http://www.w3.org/TR/domcore/#dom-node-clonenode"><code>cloneNode()</code></a> method on a <a href="#api-shadow-root"><code>ShadowRoot</code></a> instance <strong>must</strong> always throw a <a href="http://www.w3.org/TR/domcore/#dom-domexception-data_clone_err"><code>DATA_CLONE_ERR</code></a> exception.</p>


<h3 id="content-element"><span class="section">11.2</span> The <code>content</code> HTML element</h3>

<p>The <dfn id="dfn-content-element"><code>content</code></dfn> HTML element represents an <a href="#dfn-insertion-point">insertion point</a> in the <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>.</p>

<dl>
<dt>Context</dt>
<dd>Where <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#flow-content-0">flow content</a> is expected.</dd>
<dt>Content model</dt>
<dd><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#transparent">Transparent</a></dd>
<dt>Children</dt>
<dd>Anything as <a href="#dfn-fallback-content">fallback content</a></dd>
<dt>Content attributes</dt>
<dd><a href="http://dev.w3.org/html5/spec/Overview.html#global-attributes">Global attributes</a></dd>
<dd>
    <dl>
<!--    <dt id="markup-content-apply-shadow-styles"><code>apply-shadow-styles</code>, a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attribute">boolean attribute</a></dt>
    <dd>indicates whether or not the rules in the scoped styles, defined in shadow DOM subtree are applied to the <a href="#dfn-shadow-host">shadow host</a>'s children that are inserted in place of this <code>content</code> element. If present, the styles are applied.</dd> -->
    <dt id="markup-content-select"><code>select</code>, a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#comma-separated-tokens">set of comma-separated tokens</a></dt>
    <dd>
        defines the <a href="#dfn-matching-criteria">matching criteria</a> for <a href="#dfn-distribution">distributing</a> child nodes of the <a href="#dfn-shadow-host">shadow host</a>. Each token <strong>must</strong> be a valid <a href="#dfn-selector-fragment">selector fragment</a>. If any token is invalid, the entire value of the <code>select</code> attribute is considered invalid.
    </dd>
    <dt id="markup-content-reset-style-inheritance"><code>reset-style-inheritance</code>, a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attribute">boolean</a> attribute</dt>
    <dd>indicates the state of the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag for this <a href="#dfn-insertion-point">insertion point</a>. If present, the value of the flag <strong>must</strong> be set to <strong>true</strong>. Otherwise, the value <strong>must</strong> be set to <strong>false</strong>.</dd>
    </dl>
</dd>
<dt>DOM Interface</dt>
<dd>
    <pre><code>
interface <dfn id="api-html-content-element">HTMLContentElement</dfn> : <a href="http://dev.w3.org/html5/spec/Overview.html#htmlelement">HTMLElement</a> {<!--    attribute bool <a href="#api-html-content-element-apply-shadow-styles">applyShadowStyles</a>; -->
    attribute DOMString <a href="#api-html-content-element-select">select</a>;
    attribute boolean <a href="#api-html-content-element-reset-style-inheritance">resetStyleInheritance</a>;
}
    </code></pre>
    <dl>
    <dt>Attributes</dt>
    <dd>
    <dl>
<!--        <dt id="api-html-content-element-apply-shadow-styles"><code>applyShadowStyles</code> of type <code>bool</code></dt>
        <dd>Must <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#reflect">reflect</a> the <a href="#markup-content-apply-shadow-styles">apply-shadow-styles</a> attribute.</dd> -->
        <dt id="api-html-content-element-select"><code>select</code> of type <code>DOMString</code></dt>
        <dd><strong>Must</strong> <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#reflect">reflect</a> the <a href="#markup-content-select">select</a> attribute.</dd>
        <dt id="api-html-content-element-reset-style-inheritance"><code>resetStyleInheritance</code> of type <code>boolean</code></dt>
        <dd><strong>Must</strong> <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#reflect">reflect</a> the <a href="#markup-content-reset-style-inheritance">reset-style-inheritance</a> attribute.</dd>
    </dl>
    </dd>
    </dl>
</dd>
</dl>


<h3 id="shadow-element"><span class="section">11.3</span> The <code>shadow</code> HTML element</h3>

<p>The <dfn id="dfn-shadow-element"><code>shadow</code></dfn> HTML element represents an <a href="#dfn-shadow-insertion-point">shadow insertion point</a> in a <a href="#dfn-shadow-dom-subtree">shadow DOM subtree</a>.</p>

<dl>
<dt>Context</dt>
<dd>Where <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#flow-content-0">flow content</a> is expected.</dd>
<dt>Content model</dt>
<dd><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#transparent">Transparent</a></dd>
<dt>Children</dt>
<dd>Anything as <a href="#dfn-fallback-content">fallback content</a></dd>
<dt>Content attributes</dt>
<dd><a href="http://dev.w3.org/html5/spec/Overview.html#global-attributes">Global attributes</a></dd>
<dd>
<dl>
    <dt id="markup-shadow-reset-style-inheritance"><code>reset-style-inheritance</code>, a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attribute">boolean</a> attribute</dt>
    <dd>indicates the state of the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag for this <a href="#dfn-shadow-insertion-point">shadow insertion point</a>. If present, the value of the flag <strong>must</strong> be set to <strong>true</strong>. Otherwise, the value <strong>must</strong> be set to <strong>false</strong>.</dd>
</dl></dd>
<dt>DOM Interface</dt>
<dd>
    <pre><code>
interface <dfn id="api-html-shadow-element">HTMLShadowElement</dfn> : <a href="http://dev.w3.org/html5/spec/Overview.html#htmlelement">HTMLElement</a> {
    attribute boolean <a href="#api-html-shadow-element-reset-style-inheritance">resetStyleInheritance</a>;
}
    </code></pre>
    <dl>
        <dt>Attributes</dt>
        <dt id="api-html-shadow-element-reset-style-inheritance"><code>resetStyleInheritance</code> of type <code>boolean</code></dt>
        <dd><strong>Must</strong> <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#reflect">reflect</a> the <a href="#markup-shadow-reset-style-inheritance">reset-style-inheritance</a> attribute.</dd>
    </dl>
</dd>
</dl>
</section>

<h2 id="shadow-dom-example"><span class="section">12</span> Shadow DOM Example</h2>

<p>Bob was asked to turn a simple list of links into a News Widget, which has links organized into two categories: breaking news and just news. The current document markup for the stories looks like this:</p>
<pre class="prettyprint"><code><span class="pln">
</span><span class="tag">&lt;ul</span><span class="pln"> </span><span class="atn">class</span><span class="pun">=</span><span class="atv">"stories"</span><span class="tag">&gt;</span><span class="pln">
    </span><span class="tag">&lt;li&gt;&lt;a</span><span class="pln"> </span><span class="atn">href</span><span class="pun">=</span><span class="atv">"//example.com/stories/1"</span><span class="tag">&gt;</span><span class="pln">A story</span><span class="tag">&lt;/a&gt;&lt;/li&gt;</span><span class="pln">
    </span><span class="tag">&lt;li&gt;&lt;a</span><span class="pln"> </span><span class="atn">href</span><span class="pun">=</span><span class="atv">"//example.com/stories/2"</span><span class="tag">&gt;</span><span class="pln">Another story</span><span class="tag">&lt;/a&gt;&lt;/li&gt;</span><span class="pln">
    </span><span class="tag">&lt;li</span><span class="pln"> </span><span class="atn">class</span><span class="pun">=</span><span class="atv">"breaking"</span><span class="tag">&gt;&lt;a</span><span class="pln"> </span><span class="atn">href</span><span class="pun">=</span><span class="atv">"//example.com/stories/3"</span><span class="tag">&gt;</span><span class="pln">Also a story</span><span class="tag">&lt;/a&gt;&lt;/li&gt;</span><span class="pln">
    </span><span class="tag">&lt;li&gt;&lt;a</span><span class="pln"> </span><span class="atn">href</span><span class="pun">=</span><span class="atv">"//example.com/stories/4"</span><span class="tag">&gt;</span><span class="pln">Yet another story</span><span class="tag">&lt;/a&gt;&lt;/li&gt;</span><span class="pln">
    </span><span class="tag">&lt;li&gt;&lt;a</span><span class="pln"> </span><span class="atn">href</span><span class="pun">=</span><span class="atv">"//example.com/stories/4"</span><span class="tag">&gt;</span><span class="pln">Awesome story</span><span class="tag">&lt;/a&gt;&lt;/li&gt;</span><span class="pln">
    </span><span class="tag">&lt;li</span><span class="pln"> </span><span class="atn">class</span><span class="pun">=</span><span class="atv">"breaking"</span><span class="tag">&gt;&lt;a</span><span class="pln"> </span><span class="atn">href</span><span class="pun">=</span><span class="atv">"//example.com/stories/5"</span><span class="tag">&gt;</span><span class="pln">Horrible story</span><span class="tag">&lt;/a&gt;&lt;/li&gt;</span><span class="pln">
</span><span class="tag">&lt;/ul&gt;</span></code></pre>

<p>To organize the stories, Bob decides to use <strong>shadow DOM</strong>. Doing so will allow Bob to keep the document markup uncluttered, and harnessing the power of insertion point makes sorting stories by class name a very simple task. After getting another cup of <a href="http://en.wikipedia.org/wiki/List_of_coffee_beverages#Green_Eye">Green Eye</a>, he quickly mocks up the following shadow DOM subtree, to be hosted by the <code>ul</code> element:</p>
<pre class="prettyprint"><code><span class="pln">
</span><span class="tag">&lt;div</span><span class="pln"> </span><span class="atn">class</span><span class="pun">=</span><span class="atv">"breaking"</span><span class="tag">&gt;</span><span class="pln">
    </span><span class="tag">&lt;ul&gt;</span><span class="pln">
        </span><span class="tag">&lt;content</span><span class="pln"> </span><span class="atn">select</span><span class="pun">=</span><span class="atv">".breaking"</span><span class="tag">&gt;&lt;/content&gt;</span><span class="pln"> </span><span class="com">&lt;!-- insertion point for breaking news --&gt;</span><span class="pln">
    </span><span class="tag">&lt;/ul&gt;</span><span class="pln">
</span><span class="tag">&lt;/div&gt;</span><span class="pln">
</span><span class="tag">&lt;div</span><span class="pln"> </span><span class="atn">class</span><span class="pun">=</span><span class="atv">"other"</span><span class="tag">&gt;</span><span class="pln">
    </span><span class="tag">&lt;ul&gt;</span><span class="pln">
        </span><span class="tag">&lt;content&gt;&lt;/content&gt;</span><span class="pln"> </span><span class="com">&lt;!-- insertion point for the rest of the news --&gt;</span><span class="pln">
    </span><span class="tag">&lt;/ul&gt;</span><span class="pln">
</span><span class="tag">&lt;/div&gt;</span></code></pre>
<p>Bob then styles the newborn widget according to comps from the designer by adding this to the shadow DOM subtree mockup:</p>
<pre class="prettyprint"><code><span class="pln">
</span><span class="tag">&lt;style&gt;</span><span class="pln">
    div</span><span class="pun">.</span><span class="pln">breaking </span><span class="pun">{</span><span class="pln">
        color</span><span class="pun">:</span><span class="pln"> </span><span class="typ">Red</span><span class="pun">;</span><span class="pln">
        font</span><span class="pun">-</span><span class="pln">size</span><span class="pun">:</span><span class="pln"> </span><span class="lit">20px</span><span class="pun">;</span><span class="pln">
        border</span><span class="pun">:</span><span class="pln"> </span><span class="lit">1px</span><span class="pln"> dashed </span><span class="typ">Purple</span><span class="pun">;</span><span class="pln">
    </span><span class="pun">}</span><span class="pln">
    div</span><span class="pun">.</span><span class="pln">other </span><span class="pun">{</span><span class="pln">
        padding</span><span class="pun">:</span><span class="pln"> </span><span class="lit">2px</span><span class="pln"> </span><span class="lit">0</span><span class="pln"> </span><span class="lit">0</span><span class="pln"> </span><span class="lit">0</span><span class="pun">;</span><span class="pln">
        border</span><span class="pun">:</span><span class="pln"> </span><span class="lit">1px</span><span class="pln"> solid </span><span class="typ">Cyan</span><span class="pun">;</span><span class="pln">
    </span><span class="pun">}</span><span class="pln">
</span><span class="tag">&lt;/style&gt;</span></code></pre>
<p>While pondering if his company should start looking for a new designer, Bob converts the mockup to code:</p>
<pre class="prettyprint"><code><span class="pln">
</span><span class="kwd">function</span><span class="pln"> createStoryGroup</span><span class="pun">(</span><span class="pln">className</span><span class="pun">,</span><span class="pln"> contentSelector</span><span class="pun">)</span><span class="pln">
</span><span class="pun">{</span><span class="pln">
    </span><span class="kwd">var</span><span class="pln"> </span><span class="kwd">group</span><span class="pln"> </span><span class="pun">=</span><span class="pln"> document</span><span class="pun">.</span><span class="pln">createElement</span><span class="pun">(</span><span class="str">'div'</span><span class="pun">);</span><span class="pln">
    </span><span class="kwd">group</span><span class="pun">.</span><span class="pln">className </span><span class="pun">=</span><span class="pln"> className</span><span class="pun">;</span><span class="pln">
    </span><span class="com">// Empty string in select attribute or absence thereof work the same, so no need for special handling.</span><span class="pln">
    </span><span class="kwd">group</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">=</span><span class="pln"> </span><span class="str">'&lt;ul&gt;&lt;content select="'</span><span class="pln"> </span><span class="pun">+</span><span class="pln"> contentSelector </span><span class="pun">+</span><span class="pln"> </span><span class="str">'"&gt;&lt;/content&gt;&lt;/ul&gt;'</span><span class="pun">;</span><span class="pln">
    </span><span class="kwd">return</span><span class="pln"> </span><span class="kwd">group</span><span class="pun">;</span><span class="pln">
</span><span class="pun">}</span><span class="pln">

</span><span class="kwd">function</span><span class="pln"> createStyle</span><span class="pun">()</span><span class="pln">
</span><span class="pun">{</span><span class="pln">
    </span><span class="kwd">var</span><span class="pln"> style </span><span class="pun">=</span><span class="pln"> document</span><span class="pun">.</span><span class="pln">createElement</span><span class="pun">(</span><span class="str">'style'</span><span class="pun">);</span><span class="pln">
    style</span><span class="pun">.</span><span class="pln">scoped </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">true</span><span class="pun">;</span><span class="pln">
    style</span><span class="pun">.</span><span class="pln">textContent </span><span class="pun">=</span><span class="pln"> </span><span class="str">'div.breaking { color: Red;font-size: 20px; border: 1px dashed Purple; }'</span><span class="pln"> </span><span class="pun">+</span><span class="pln">
        </span><span class="str">'div.other { padding: 2px 0 0 0; border: 1px solid Cyan; }'</span><span class="pun">;</span><span class="pln">
    </span><span class="kwd">return</span><span class="pln"> style</span><span class="pun">;</span><span class="pln">
</span><span class="pun">}</span><span class="pln">

</span><span class="kwd">function</span><span class="pln"> makeShadowSubtree</span><span class="pun">(</span><span class="pln">storyList</span><span class="pun">)</span><span class="pln">
</span><span class="pun">{</span><span class="pln">
    </span><span class="kwd">var</span><span class="pln"> root </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">new</span><span class="pln"> </span><span class="typ">ShadowRoot</span><span class="pun">(</span><span class="pln">storyList</span><span class="pun">);</span><span class="pln">
    root</span><span class="pun">.</span><span class="pln">appendChild</span><span class="pun">(</span><span class="pln">createStyle</span><span class="pun">());</span><span class="pln">
    root</span><span class="pun">.</span><span class="pln">appendChild</span><span class="pun">(</span><span class="pln">createStoryGroup</span><span class="pun">(</span><span class="str">'breaking'</span><span class="pun">,</span><span class="pln"> </span><span class="str">'.breaking'</span><span class="pun">));</span><span class="pln">
    root</span><span class="pun">.</span><span class="pln">appendChild</span><span class="pun">(</span><span class="pln">createStoryGroup</span><span class="pun">(</span><span class="str">'other'</span><span class="pun">,</span><span class="pln"> </span><span class="str">''</span><span class="pun">));</span><span class="pln">
</span><span class="pun">}</span><span class="pln">

document</span><span class="pun">.</span><span class="pln">addEventListener</span><span class="pun">(</span><span class="str">'DOMContentLoaded'</span><span class="pun">,</span><span class="pln"> </span><span class="kwd">function</span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
    </span><span class="pun">[].</span><span class="pln">forEach</span><span class="pun">.</span><span class="pln">call</span><span class="pun">(</span><span class="pln">document</span><span class="pun">.</span><span class="pln">querySelectorAll</span><span class="pun">(</span><span class="str">'ul.stories'</span><span class="pun">),</span><span class="pln"> makeShadowSubtree</span><span class="pun">);</span><span class="pln">
</span><span class="pun">});</span></code></pre>

<p>Well done, Bob! With the cup of coffee still half-full, the work is complete. Recognizing his awesomeness, Bob returns to teaching n00bs the ways of <a href="http://en.wikipedia.org/wiki/World_of_Warcraft">WoW</a>.</p>

<p>A few months pass.</p>

<p>It's election time. With Bob at his annual conference, Alice is charged with adding <strong>another</strong>, temporary box to the news widget, filled with election-related stories. Alice studies Bob's code, reads up on the shadow DOM spec and realizes that, thanks to multiple shadow DOM subtree support, she doesn't have to touch his code. As usual, her solution is elegant and simple, fitting neatly right under Bob's code:</p>
<pre class="prettyprint"><code><span class="pln">
</span><span class="com">// TODO(alice): BEGIN -- DELETE THIS CODE AFTER ELECTIONS ARE OVER.</span><span class="pln">
</span><span class="kwd">var</span><span class="pln"> ELECTION_BOX_REMOVAL_DEADLINE </span><span class="pun">=</span><span class="pln"> </span><span class="pun">...;</span><span class="pln">

</span><span class="kwd">function</span><span class="pln"> createElectionStyle</span><span class="pun">()</span><span class="pln">
</span><span class="pun">{</span><span class="pln">
    </span><span class="kwd">var</span><span class="pln"> style </span><span class="pun">=</span><span class="pln"> document</span><span class="pun">.</span><span class="pln">createElement</span><span class="pun">(</span><span class="str">'style'</span><span class="pun">);</span><span class="pln">
    style</span><span class="pun">.</span><span class="pln">scoped </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">true</span><span class="pun">;</span><span class="pln">
    </span><span class="com">// TODO(alice): Check designer's desk for hallucinogens.</span><span class="pln">
    style</span><span class="pun">.</span><span class="pln">textContent </span><span class="pun">=</span><span class="pln"> </span><span class="str">'div.election { color: Magenta;font-size: 24px; border: 2px dotted Fuchsia; }'</span><span class="pun">;</span><span class="pln">
    </span><span class="kwd">return</span><span class="pln"> style</span><span class="pun">;</span><span class="pln">
</span><span class="pun">}</span><span class="pln">

</span><span class="kwd">function</span><span class="pln"> makeElectionShadowSubtree</span><span class="pun">(</span><span class="pln">storyList</span><span class="pun">)</span><span class="pln">
</span><span class="pun">{</span><span class="pln">
    </span><span class="kwd">var</span><span class="pln"> root </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">new</span><span class="pln"> </span><span class="typ">ShadowRoot</span><span class="pun">(</span><span class="pln">storyList</span><span class="pun">);</span><span class="pln">
    </span><span class="com">// Add and style election story box.</span><span class="pln">
    root</span><span class="pun">.</span><span class="pln">appendChild</span><span class="pun">(</span><span class="pln">createElectionStyle</span><span class="pun">());</span><span class="pln">
    root</span><span class="pun">.</span><span class="pln">appendChild</span><span class="pun">(</span><span class="pln">createStoryGroup</span><span class="pun">(</span><span class="str">'election'</span><span class="pun">,</span><span class="pln"> </span><span class="str">'.election'</span><span class="pun">));</span><span class="pln">
    </span><span class="com">// Insert Bob's shadow tree under the election story box.</span><span class="pln">
    root</span><span class="pun">.</span><span class="pln">appendChild</span><span class="pun">(</span><span class="pln">document</span><span class="pun">.</span><span class="pln">createElement</span><span class="pun">(</span><span class="str">'shadow'</span><span class="pun">));</span><span class="pln">
</span><span class="pun">}</span><span class="pln">

</span><span class="kwd">if</span><span class="pln"> </span><span class="pun">(</span><span class="typ">Date</span><span class="pun">.</span><span class="pln">now</span><span class="pun">()</span><span class="pln"> </span><span class="pun">&lt;</span><span class="pln"> ELECTION_BOX_REMOVAL_DEADLINE</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
    document</span><span class="pun">.</span><span class="pln">addEventListener</span><span class="pun">(</span><span class="str">'DOMContentLoaded'</span><span class="pun">,</span><span class="pln"> </span><span class="kwd">function</span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
        </span><span class="pun">[].</span><span class="pln">forEach</span><span class="pun">.</span><span class="pln">call</span><span class="pun">(</span><span class="pln">document</span><span class="pun">.</span><span class="pln">querySelectorAll</span><span class="pun">(</span><span class="str">'ul.stories'</span><span class="pun">),</span><span class="pln"> makeElectionShadowSubtree</span><span class="pun">);</span><span class="pln">
    </span><span class="pun">});</span><span class="pln">
</span><span class="pun">}</span><span class="pln">
</span><span class="com">// TODO(alice): END -- DELETE THIS CODE AFTER ELECTIONS ARE OVER.</span></code></pre>
<p>Using the <code>shadow</code> element allows Alice to compose Bob's widget <strong>inside</strong> of hers—without having to change a line of production code. Smiling to herself, Alice realizes that Bob may have come up with a way to keep the document markup clean, but <strong>she</strong> is the one who takes the cake for using shadow DOM subtree composition in such a cool way.</p>

</section>


<h2 id="acknowledgements">Acknowledgements</h2>

<p><span class="vcard">David Hyatt</span> developed <a href="http://dev.w3.org/2006/xbl2/">XBL 1.0</a>, and <span class="vcard">Ian Hickson</span> co-wrote <a href="http://dev.w3.org/2006/xbl2/">XBL 2.0</a>. These documents provided tremendous insight into the problem of functional encapsulation and greatly influenced this specification.</p>

<p><span class="vcard">Alex Russell</span> and his considerable forethought triggered a new wave of enthusiasm around the subject of shadow DOM and how it can be applied practically on the Web.</p>

<p><span class="vcard">Dominic Cooney</span>, <span class="vcard">Hajime Morrita</span>, and <span class="vcard">Roland Steiner</span> worked tirelessly to scope the problem of functional encapsulation within the confines of the Web platform and provided a solid foundation for this document.</p>

<p>The editor would also like to thank <span class="vcard">Alex Komoroske</span>, <span class="vcard">Anne van Kesteren</span>, <span class="vcard">Brian Kardell</span>, <span class="vcard">Darin Fisher</span>, <span class="vcard">Deepak Sherveghar</span>, <span class="vcard">Edward O'Connor</span>, <span class="vcard">Elisée Maurer</span>, <span class="vcard">Erik Arvidsson</span>, <span class="vcard">Glenn Adams</span>, <span class="vcard">Hayato Ito</span>, <span class="vcard">Jonas Sicking</span>, <span class="vcard">Malte Ubl</span>, <span class="vcard">Oliver Nightingale</span>, <span class="vcard">Olli Pettay</span>, <span class="vcard">Rafael Weinstein</span>, <span class="vcard">Richard Bradshaw</span>, <span class="vcard">Ruud Steltenpool</span>, <span class="vcard">Sam Dutton</span>, <span class="vcard">Shinya Kawanaka</span>, <span class="vcard">Tab Atkins</span>, and <span class="vcard">Takashi Sakamoto</span> for their comments and contributions to this specification.</p>

<p>This list is too short. There's a lot of work left to do. Please contribute by reviewing and filing bugs—and don't forget to ask the editor to add your name into this section.</p>



</body></html>
